nshconfig


Namenshconfig JSON
Version 0.17.2 PyPI version JSON
download
home_pageNone
SummaryFully typed configuration management, powered by Pydantic
upload_time2024-10-01 00:49:44
maintainerNone
docs_urlNone
authorNima Shoghi
requires_python<4.0,>=3.10
licenseNone
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # nshconfig

Fully typed configuration management, powered by [Pydantic](https://github.com/pydantic/pydantic/)

## Motivation

As a machine learning researcher, I often found myself running numerous training jobs with various hyperparameters for the models I was working on. Keeping track of these parameters in a fully typed manner became increasingly important. While the excellent `pydantic` library provided most of the functionality I needed, I wanted to add a few extra features to streamline my workflow. This led to the creation of `nshconfig`.


## Installation

You can install `nshconfig` via pip:

```bash
pip install nshconfig
```

## Usage

While the primary use case for `nshconfig` is in machine learning projects, it can be used in any Python project where you need to store configurations in a fully typed manner.

Here's a basic example of how to use `nshconfig`:

```python
import nshconfig as C

class MyConfig(C.Config):
    field1: int
    field2: str
    field3: C.AllowMissing[float] = C.MISSING

config = MyConfig.draft()
config.field1 = 42
config.field2 = "hello"
final_config = config.finalize()

print(final_config)
```

For more advanced usage and examples, please refer to the documentation.

## Features

### Draft Configs

Draft configs allow for a nicer API when creating configurations. Instead of relying on JSON or YAML files, you can create your configs using pure Python:

```python
config = MyConfig.draft()

# Set some values
config.a = 10
config.b = "hello"

# Finalize the config
config = config.finalize()
```

This approach enables a more intuitive and expressive way of defining your configurations.

#### Motivation

The primary motivation behind draft configs is to provide a cleaner and more Pythonic way of creating configurations. By leveraging the power of Python, you can define your configs in a more readable and maintainable manner.

#### Usage Guide

1. Create a draft config using the `draft()` class method:
   ```python
   config = MyConfig.draft()
   ```

2. Set the desired values on the draft config:
   ```python
   config.field1 = value1
   config.field2 = value2
   ```

3. Finalize the draft config to obtain the validated configuration:
   ```python
   final_config = config.finalize()
   ```

### MISSING Constant

The `MISSING` constant is similar to `None`, but with a key difference. While `None` has the type `NoneType` and can only be assigned to fields of type `T | None`, the `MISSING` constant has the type `Any` and can be assigned to fields of any type.

#### Motivation

The `MISSING` constant addresses a common issue when working with optional fields in configurations. Consider the following example:

```python
import nshconfig as C

# Without MISSING:
class MyConfigWithoutMissing(C.Config):
    age: int
    age_str: str | None = None

    def __post_init__(self):
        if self.age_str is None:
            self.age_str = str(self.age)

config = MyConfigWithoutMissing(age=10)
age_str_lower = config.age_str.lower()
# ^ The above line is valid code, but the type-checker will complain because `age_str` could be `None`.
```

In the above code, the type-checker will raise a complaint because `age_str` could be `None`. This is where the `MISSING` constant comes in handy:

```python
# With MISSING:
class MyConfigWithMissing(C.Config):
    age: int
    age_str: C.AllowMissing[str] = C.MISSING

    def __post_init__(self):
        if self.age_str is C.MISSING:
            self.age_str = str(self.age)

config = MyConfigWithMissing(age=10)
age_str_lower = config.age_str.lower()
# ^ No more type-checker complaints!
```

By using the `MISSING` constant, you can indicate that a field is not set during construction, and the type-checker will not raise any complaints.

### Seamless Integration with PyTorch Lightning

`nshconfig` seamlessly integrates with PyTorch Lightning by implementing the `Mapping` interface. This allows you to use your configs directly as the `hparams` argument in your Lightning modules without any additional effort.

## Credit

`nshconfig` is built on top of the incredible [`pydantic`](https://github.com/pydantic/pydantic/) library. Massive credit goes to the [`pydantic`](https://github.com/pydantic/pydantic/) team for creating such a powerful and flexible tool for data validation and settings management.

## Contributing

Contributions are welcome! If you find any issues or have suggestions for improvement, please open an issue or submit a pull request on the GitHub repository.

## License

`nshconfig` is open-source software licensed under the [MIT License](LICENSE).

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "nshconfig",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.10",
    "maintainer_email": null,
    "keywords": null,
    "author": "Nima Shoghi",
    "author_email": "nimashoghi@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/28/38/3738890b8c37a18cfdb796f82f45f48e22ad073f2b595cdbd7da2d725650/nshconfig-0.17.2.tar.gz",
    "platform": null,
    "description": "# nshconfig\n\nFully typed configuration management, powered by [Pydantic](https://github.com/pydantic/pydantic/)\n\n## Motivation\n\nAs a machine learning researcher, I often found myself running numerous training jobs with various hyperparameters for the models I was working on. Keeping track of these parameters in a fully typed manner became increasingly important. While the excellent `pydantic` library provided most of the functionality I needed, I wanted to add a few extra features to streamline my workflow. This led to the creation of `nshconfig`.\n\n\n## Installation\n\nYou can install `nshconfig` via pip:\n\n```bash\npip install nshconfig\n```\n\n## Usage\n\nWhile the primary use case for `nshconfig` is in machine learning projects, it can be used in any Python project where you need to store configurations in a fully typed manner.\n\nHere's a basic example of how to use `nshconfig`:\n\n```python\nimport nshconfig as C\n\nclass MyConfig(C.Config):\n    field1: int\n    field2: str\n    field3: C.AllowMissing[float] = C.MISSING\n\nconfig = MyConfig.draft()\nconfig.field1 = 42\nconfig.field2 = \"hello\"\nfinal_config = config.finalize()\n\nprint(final_config)\n```\n\nFor more advanced usage and examples, please refer to the documentation.\n\n## Features\n\n### Draft Configs\n\nDraft configs allow for a nicer API when creating configurations. Instead of relying on JSON or YAML files, you can create your configs using pure Python:\n\n```python\nconfig = MyConfig.draft()\n\n# Set some values\nconfig.a = 10\nconfig.b = \"hello\"\n\n# Finalize the config\nconfig = config.finalize()\n```\n\nThis approach enables a more intuitive and expressive way of defining your configurations.\n\n#### Motivation\n\nThe primary motivation behind draft configs is to provide a cleaner and more Pythonic way of creating configurations. By leveraging the power of Python, you can define your configs in a more readable and maintainable manner.\n\n#### Usage Guide\n\n1. Create a draft config using the `draft()` class method:\n   ```python\n   config = MyConfig.draft()\n   ```\n\n2. Set the desired values on the draft config:\n   ```python\n   config.field1 = value1\n   config.field2 = value2\n   ```\n\n3. Finalize the draft config to obtain the validated configuration:\n   ```python\n   final_config = config.finalize()\n   ```\n\n### MISSING Constant\n\nThe `MISSING` constant is similar to `None`, but with a key difference. While `None` has the type `NoneType` and can only be assigned to fields of type `T | None`, the `MISSING` constant has the type `Any` and can be assigned to fields of any type.\n\n#### Motivation\n\nThe `MISSING` constant addresses a common issue when working with optional fields in configurations. Consider the following example:\n\n```python\nimport nshconfig as C\n\n# Without MISSING:\nclass MyConfigWithoutMissing(C.Config):\n    age: int\n    age_str: str | None = None\n\n    def __post_init__(self):\n        if self.age_str is None:\n            self.age_str = str(self.age)\n\nconfig = MyConfigWithoutMissing(age=10)\nage_str_lower = config.age_str.lower()\n# ^ The above line is valid code, but the type-checker will complain because `age_str` could be `None`.\n```\n\nIn the above code, the type-checker will raise a complaint because `age_str` could be `None`. This is where the `MISSING` constant comes in handy:\n\n```python\n# With MISSING:\nclass MyConfigWithMissing(C.Config):\n    age: int\n    age_str: C.AllowMissing[str] = C.MISSING\n\n    def __post_init__(self):\n        if self.age_str is C.MISSING:\n            self.age_str = str(self.age)\n\nconfig = MyConfigWithMissing(age=10)\nage_str_lower = config.age_str.lower()\n# ^ No more type-checker complaints!\n```\n\nBy using the `MISSING` constant, you can indicate that a field is not set during construction, and the type-checker will not raise any complaints.\n\n### Seamless Integration with PyTorch Lightning\n\n`nshconfig` seamlessly integrates with PyTorch Lightning by implementing the `Mapping` interface. This allows you to use your configs directly as the `hparams` argument in your Lightning modules without any additional effort.\n\n## Credit\n\n`nshconfig` is built on top of the incredible [`pydantic`](https://github.com/pydantic/pydantic/) library. Massive credit goes to the [`pydantic`](https://github.com/pydantic/pydantic/) team for creating such a powerful and flexible tool for data validation and settings management.\n\n## Contributing\n\nContributions are welcome! If you find any issues or have suggestions for improvement, please open an issue or submit a pull request on the GitHub repository.\n\n## License\n\n`nshconfig` is open-source software licensed under the [MIT License](LICENSE).\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Fully typed configuration management, powered by Pydantic",
    "version": "0.17.2",
    "project_urls": {
        "homepage": "https://github.com/nimashoghi/nshconfig"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "a1f228fe8a47146231592c1a0c4749c8c006c48f353bc1f47753e5ce2a0e801f",
                "md5": "1e23f389eec5541975a120c561fa3cbb",
                "sha256": "24d8bb697a4e05c4c032f6e02e7a90d61521d8a93a534983367e486a7b308526"
            },
            "downloads": -1,
            "filename": "nshconfig-0.17.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "1e23f389eec5541975a120c561fa3cbb",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.10",
            "size": 15367,
            "upload_time": "2024-10-01T00:49:43",
            "upload_time_iso_8601": "2024-10-01T00:49:43.124901Z",
            "url": "https://files.pythonhosted.org/packages/a1/f2/28fe8a47146231592c1a0c4749c8c006c48f353bc1f47753e5ce2a0e801f/nshconfig-0.17.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "28383738890b8c37a18cfdb796f82f45f48e22ad073f2b595cdbd7da2d725650",
                "md5": "d1de0c0b88a1878f209588d001ae764f",
                "sha256": "8072aa034603a2ab0a6d69590e66363e8e2a0c9dfae2d6f42948af86df746475"
            },
            "downloads": -1,
            "filename": "nshconfig-0.17.2.tar.gz",
            "has_sig": false,
            "md5_digest": "d1de0c0b88a1878f209588d001ae764f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.10",
            "size": 14291,
            "upload_time": "2024-10-01T00:49:44",
            "upload_time_iso_8601": "2024-10-01T00:49:44.515972Z",
            "url": "https://files.pythonhosted.org/packages/28/38/3738890b8c37a18cfdb796f82f45f48e22ad073f2b595cdbd7da2d725650/nshconfig-0.17.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-10-01 00:49:44",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "nimashoghi",
    "github_project": "nshconfig",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "nshconfig"
}
        
Elapsed time: 0.49789s