# traitlets

> Traitlets Python configuration system

- **URL**: https://www.freshcrate.ai/projects/traitlets
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `v5.15.1` (2026-06-03)
- **License**: non-standard
- **Source**: https://github.com/ipython/traitlets
- **Homepage**: https://pypi.org/project/traitlets/
- **Language**: Python
- **GitHub**: 649 stars, 208 forks
- **Registry**: pypi (`traitlets`)
- **Tags**: `interactive`, `interpreter`, `pypi`, `shell`, `web`

## Description

# Traitlets

[![Tests](https://github.com/ipython/traitlets/actions/workflows/tests.yml/badge.svg)](https://github.com/ipython/traitlets/actions/workflows/tests.yml)
[![Documentation Status](https://readthedocs.org/projects/traitlets/badge/?version=latest)](https://traitlets.readthedocs.io/en/latest/?badge=latest)
[![Tidelift](https://tidelift.com/subscription/pkg/pypi-traitlets)](https://tidelift.com/badges/package/pypi/traitlets)

|               |                                      |
| ------------- | ------------------------------------ |
| **home**      | https://github.com/ipython/traitlets |
| **pypi-repo** | https://pypi.org/project/traitlets/  |
| **docs**      | https://traitlets.readthedocs.io/    |
| **license**   | Modified BSD License                 |

Traitlets is a pure Python library enabling:

- the enforcement of strong typing for attributes of Python objects
  (typed attributes are called _"traits"_);
- dynamically calculated default values;
- automatic validation and coercion of trait attributes when attempting a
  change;
- registering for receiving notifications when trait values change;
- reading configuring values from files or from command line
  arguments - a distinct layer on top of traitlets, so you may use
  traitlets without the configuration machinery.

Its implementation relies on the [descriptor](https://docs.python.org/howto/descriptor.html)
pattern, and it is a lightweight pure-python alternative of the
[_traits_ library](https://docs.enthought.com/traits/).

Traitlets powers the configuration system of IPython and Jupyter
and the declarative API of IPython interactive widgets.

## Installation

For a local installation, make sure you have
[pip installed](https://pip.pypa.io/en/stable/installing/) and run:

```bash
pip install traitlets
```

For a **development installation**, clone this repository, change into the
`traitlets` root directory, and run pip:

```bash
git clone https://github.com/ipython/traitlets.git
cd traitlets
pip install -e .
```

## Running the tests

```bash
pip install "traitlets[test]"
py.test traitlets
```

## Code Styling

`traitlets` has adopted automatic code formatting so you shouldn't
need to worry too much about your code style.
As long as your code is valid,
the pre-commit hook should take care of how it should look.

To install `pre-commit` locally, run the following::

```
pip install pre-commit
pre-commit install
```

You can invoke the pre-commit hook by hand at any time with::

```
pre-commit run
```

which should run any autoformatting on your code
and tell you about any errors it couldn't fix automatically.
You may also install [black integration](https://github.com/psf/black#editor-integration)
into your text editor to format code automatically.

If you have already committed files before setting up the pre-commit
hook with `pre-commit install`, you can fix everything up using
`pre-commit run --all-files`. You need to make the fixing commit
yourself after that.

Some of the hooks only run on CI by default, but you can invoke them by
running with the `--hook-stage manual` argument.

## Usage

Any class with trait attributes must inherit from `HasTraits`.
For the list of available trait types and their properties, see the
[Trait Types](https://traitlets.readthedocs.io/en/latest/trait_types.html)
section of the documentation.

### Dynamic default values

To calculate a default value dynamically, decorate a method of your class with
`@default({traitname})`. This method will be called on the instance, and
should return the default value. In this example, the `_username_default`
method is decorated with `@default('username')`:

```Python
import getpass
from traitlets import HasTraits, Unicode, default

class Identity(HasTraits):
    username = Unicode()

    @default('username')
    def _username_default(self):
        return getpass.getuser()
```

### Callbacks when a trait attribute changes

When a trait changes, an application can follow this trait change with
additional actions.

To do something when a trait attribute is changed, decorate a method with
[`traitlets.observe()`](https://traitlets.readthedocs.io/en/latest/api.html?highlight=observe#traitlets.observe).
The method will be called with a single argument, a dictionary which contains
an owner, new value, old value, name of the changed trait, and the event type.

In this example, the `_num_changed` method is decorated with `` @observe(`num`) ``:

```Python
from traitlets import HasTraits, Integer, observe

class TraitletsExample(HasTraits):
    num = Integer(5, help="a number").tag(config=True)

    @observe('num')
    def _num_changed(self, change):
        print("{name} changed from {old} to {new}".format(**change))
```

and is passed the following dictionary when called:

```Python
{
  'owner': object,  # The HasTraits instance
  'new': 6,         # The new value
  'old': 5,         # The old value
  'name': "foo",    # The name of the changed trait
  'type': 'change', # The

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v5.15.1` | 2026-06-03 | High | ## 5.15.1  ([Full Changelog](https://github.com/ipython/traitlets/compare/v5.15.0...bc0b8b51f1adab7671b6e3932d91844c05731660))  ### Maintenance and upkeep improvements  - Fix CI (docs build, mypy tests, downstream) [#943](https://github.com/ipython/traitlets/pull/943) ([@Carreau](https://github.com/Carreau), [@krassowski](https://github.com/krassowski))  ### Contributors to this release  The following people contributed discussions, new ideas, code and documentation contributions, and review. |
| `v5.15.0` | 2026-05-06 | High | ## 5.15.0  ([Full Changelog](https://github.com/ipython/traitlets/compare/v5.14.3...8c2b92efa3238961b74cc1dc6497722e41da5472))  ### Enhancements made  - Moved definitions of K and V outside of TYPE_CHECKING condition [#935](https://github.com/ipython/traitlets/pull/935) ([@JohanMabille](https://github.com/JohanMabille), [@Carreau](https://github.com/Carreau)) - Accept integer-valued numbers for Integer [#919](https://github.com/ipython/traitlets/pull/919) ([@minrk](https://github.com/minrk), [ |
| `5.14.3` | 2026-04-21 | Low | Imported from PyPI (5.14.3) |
| `v5.14.3` | 2024-04-19 | Low | ## 5.14.3  ([Full Changelog](https://github.com/ipython/traitlets/compare/v5.14.2...5cf34f6c42b6e39aa1e53394443efca3d7329e3b))  ### Bugs fixed  - Fix assigning string value to Set [#903](https://github.com/ipython/traitlets/pull/903) ([@azjps](https://github.com/azjps))  ### Maintenance and upkeep improvements  - Bump the actions group with 1 update [#899](https://github.com/ipython/traitlets/pull/899) ([@dependabot](https://github.com/dependabot))  ### Contributors to this release  ([GitHub c |
| `v5.14.3` | 2024-04-19 | Low | ## 5.14.3  ([Full Changelog](https://github.com/ipython/traitlets/compare/v5.14.2...5cf34f6c42b6e39aa1e53394443efca3d7329e3b))  ### Bugs fixed  - Fix assigning string value to Set [#903](https://github.com/ipython/traitlets/pull/903) ([@azjps](https://github.com/azjps))  ### Maintenance and upkeep improvements  - Bump the actions group with 1 update [#899](https://github.com/ipython/traitlets/pull/899) ([@dependabot](https://github.com/dependabot))  ### Contributors to this release  ([GitHub c |
| `v5.14.3` | 2024-04-19 | Low | ## 5.14.3  ([Full Changelog](https://github.com/ipython/traitlets/compare/v5.14.2...5cf34f6c42b6e39aa1e53394443efca3d7329e3b))  ### Bugs fixed  - Fix assigning string value to Set [#903](https://github.com/ipython/traitlets/pull/903) ([@azjps](https://github.com/azjps))  ### Maintenance and upkeep improvements  - Bump the actions group with 1 update [#899](https://github.com/ipython/traitlets/pull/899) ([@dependabot](https://github.com/dependabot))  ### Contributors to this release  ([GitHub c |
| `v5.14.3` | 2024-04-19 | Low | ## 5.14.3  ([Full Changelog](https://github.com/ipython/traitlets/compare/v5.14.2...5cf34f6c42b6e39aa1e53394443efca3d7329e3b))  ### Bugs fixed  - Fix assigning string value to Set [#903](https://github.com/ipython/traitlets/pull/903) ([@azjps](https://github.com/azjps))  ### Maintenance and upkeep improvements  - Bump the actions group with 1 update [#899](https://github.com/ipython/traitlets/pull/899) ([@dependabot](https://github.com/dependabot))  ### Contributors to this release  ([GitHub c |
| `v5.14.3` | 2024-04-19 | Low | ## 5.14.3  ([Full Changelog](https://github.com/ipython/traitlets/compare/v5.14.2...5cf34f6c42b6e39aa1e53394443efca3d7329e3b))  ### Bugs fixed  - Fix assigning string value to Set [#903](https://github.com/ipython/traitlets/pull/903) ([@azjps](https://github.com/azjps))  ### Maintenance and upkeep improvements  - Bump the actions group with 1 update [#899](https://github.com/ipython/traitlets/pull/899) ([@dependabot](https://github.com/dependabot))  ### Contributors to this release  ([GitHub c |
| `v5.14.3` | 2024-04-19 | Low | ## 5.14.3  ([Full Changelog](https://github.com/ipython/traitlets/compare/v5.14.2...5cf34f6c42b6e39aa1e53394443efca3d7329e3b))  ### Bugs fixed  - Fix assigning string value to Set [#903](https://github.com/ipython/traitlets/pull/903) ([@azjps](https://github.com/azjps))  ### Maintenance and upkeep improvements  - Bump the actions group with 1 update [#899](https://github.com/ipython/traitlets/pull/899) ([@dependabot](https://github.com/dependabot))  ### Contributors to this release  ([GitHub c |
| `v5.14.3` | 2024-04-19 | Low | ## 5.14.3  ([Full Changelog](https://github.com/ipython/traitlets/compare/v5.14.2...5cf34f6c42b6e39aa1e53394443efca3d7329e3b))  ### Bugs fixed  - Fix assigning string value to Set [#903](https://github.com/ipython/traitlets/pull/903) ([@azjps](https://github.com/azjps))  ### Maintenance and upkeep improvements  - Bump the actions group with 1 update [#899](https://github.com/ipython/traitlets/pull/899) ([@dependabot](https://github.com/dependabot))  ### Contributors to this release  ([GitHub c |

## Citation

- HTML: https://www.freshcrate.ai/projects/traitlets
- Markdown: https://www.freshcrate.ai/projects/traitlets.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/traitlets/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._