# Elysia
[](https://pypi.org/project/elysia)
[](https://pypi.org/project/elysia)
[](https://github.com/celsiusnarhwal/elysia/releases)
[](https://github.com/celsiusnarhwal/elysia/blob/main/LICENSE.md)
[](https://github.com/psf/black)
Elysia is an addon for [_attrs_](https://attrs.org) that provides an alternative API for creating fields on
`@define`d classes.
## Installation
```bash
pip install elysia
```
## Usage
Elysia's sole export is the `Fields` class, which wraps `attrs.field`, `attrs.setters`, and `attrs.validators` to
provide a more concise API for defining instance attributes.
Here's a brief example of a class created with _attrs_ and Elysia:
```python
from datetime import datetime
from attrs import define
from elysia import Fields
@define
class User:
name: str = Fields.field()
password: str = Fields.field(
on_setattr=Fields.setters.validate,
validator=Fields.validators.min_len(8)
)
created_at: datetime = Fields.attr(factory=datetime.utcnow, frozen=True)
```
The `User` class has two `__init__` arguments: `name` and `password`. Whenever set, `password` is validated to
ensure it's at least 8 characters long.
`User` also has a `created_at` attribute that can't set via an `__init__` argument. When a `User` object is
instantiated, `created_at` is set to the current time and cannot be changed afterwards.
### So...how does all that work, exactly?
Glad you asked.
There are two ways to define an attribute with Elysia: `Fields.field()` and `Fields.attr()`. `Fields.field()` defines
attributes that map to `__init__` arguments; `Fields.attr()` defines attributes that do not. Both are wrappers around
`attrs.field` and accept all the same arguments. Like `attrs.field`, all arguments to `Fields.field()`
and `Fields.attr()` are keyword-only.
Both methods also accept an optional, boolean, `frozen` argument. Setting it to `True` is a shortcut
for `on_setattr=attrs.setters.frozen` — that is, it freezes the attribute, raising an exception if you try to set it
after initialization.
> **Warning**
>
> Elysia is happy to combine `frozen=True` with anything else you pass to `on_setattr`, but `attrs.setters.frozen`
> will be applied _first_, which may not be what you expect.
Fields also provides access to _attrs_' setters and validators via `Fields.setters` and `Fields.validators`,
respectively. It makes no difference whether setters and validators are accessed through `Fields` or `attrs`. Do what
you like.
## License
Elysia is licensed under the [MIT License](https://github.com/celsiusnarhwal/elysia/blob/main/LICENSE.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/celsiusnarhwal/elysia",
"name": "elysia",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "attrs,class,attribute",
"author": "celsius narhwal",
"author_email": "hello@celsiusnarhwal.dev",
"download_url": "https://files.pythonhosted.org/packages/ab/de/67b9761b33016a3b3ef06bd385fe8446f4e8b2ea3ad972f52d5010678c93/elysia-1.1.1.tar.gz",
"platform": null,
"description": "# Elysia\n\n[](https://pypi.org/project/elysia)\n[](https://pypi.org/project/elysia)\n[](https://github.com/celsiusnarhwal/elysia/releases)\n[](https://github.com/celsiusnarhwal/elysia/blob/main/LICENSE.md)\n[](https://github.com/psf/black)\n\nElysia is an addon for [_attrs_](https://attrs.org) that provides an alternative API for creating fields on\n`@define`d classes.\n\n## Installation\n\n```bash\npip install elysia\n```\n\n## Usage\n\nElysia's sole export is the `Fields` class, which wraps `attrs.field`, `attrs.setters`, and `attrs.validators` to\nprovide a more concise API for defining instance attributes.\n\nHere's a brief example of a class created with _attrs_ and Elysia:\n\n```python\nfrom datetime import datetime\n\nfrom attrs import define\nfrom elysia import Fields\n\n\n@define\nclass User:\n name: str = Fields.field()\n password: str = Fields.field(\n on_setattr=Fields.setters.validate,\n validator=Fields.validators.min_len(8)\n )\n\n created_at: datetime = Fields.attr(factory=datetime.utcnow, frozen=True)\n```\n\nThe `User` class has two `__init__` arguments: `name` and `password`. Whenever set, `password` is validated to\nensure it's at least 8 characters long.\n\n`User` also has a `created_at` attribute that can't set via an `__init__` argument. When a `User` object is\ninstantiated, `created_at` is set to the current time and cannot be changed afterwards.\n\n### So...how does all that work, exactly?\n\nGlad you asked.\n\nThere are two ways to define an attribute with Elysia: `Fields.field()` and `Fields.attr()`. `Fields.field()` defines\nattributes that map to `__init__` arguments; `Fields.attr()` defines attributes that do not. Both are wrappers around\n`attrs.field` and accept all the same arguments. Like `attrs.field`, all arguments to `Fields.field()`\nand `Fields.attr()` are keyword-only.\n\nBoth methods also accept an optional, boolean, `frozen` argument. Setting it to `True` is a shortcut\nfor `on_setattr=attrs.setters.frozen` \u2014 that is, it freezes the attribute, raising an exception if you try to set it\nafter initialization.\n\n> **Warning**\n>\n> Elysia is happy to combine `frozen=True` with anything else you pass to `on_setattr`, but `attrs.setters.frozen`\n> will be applied _first_, which may not be what you expect.\n\nFields also provides access to _attrs_' setters and validators via `Fields.setters` and `Fields.validators`,\nrespectively. It makes no difference whether setters and validators are accessed through `Fields` or `attrs`. Do what\nyou like.\n\n## License\n\nElysia is licensed under the [MIT License](https://github.com/celsiusnarhwal/elysia/blob/main/LICENSE.md).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An alternative API for creating attrs fields",
"version": "1.1.1",
"split_keywords": [
"attrs",
"class",
"attribute"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c3da1e089a52feecb5e5b776e06afce515eedff616469a88837a76e9c7de49b5",
"md5": "d201f21fa64fd5f51903ea389b82e806",
"sha256": "3fc07c5c4e42c3e32fbc3b830a379fc7edea03c825627c1c46a98660fa88fd1d"
},
"downloads": -1,
"filename": "elysia-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d201f21fa64fd5f51903ea389b82e806",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 3997,
"upload_time": "2023-03-27T17:52:04",
"upload_time_iso_8601": "2023-03-27T17:52:04.883129Z",
"url": "https://files.pythonhosted.org/packages/c3/da/1e089a52feecb5e5b776e06afce515eedff616469a88837a76e9c7de49b5/elysia-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "abde67b9761b33016a3b3ef06bd385fe8446f4e8b2ea3ad972f52d5010678c93",
"md5": "f8b9d463b6b2db98781ad9097959d210",
"sha256": "1f45374f994ae86833d59200c960bd0aaccdb5ccc65f5d7a6bbe3fc8376f7976"
},
"downloads": -1,
"filename": "elysia-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f8b9d463b6b2db98781ad9097959d210",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 3441,
"upload_time": "2023-03-27T17:52:06",
"upload_time_iso_8601": "2023-03-27T17:52:06.451463Z",
"url": "https://files.pythonhosted.org/packages/ab/de/67b9761b33016a3b3ef06bd385fe8446f4e8b2ea3ad972f52d5010678c93/elysia-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-27 17:52:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "celsiusnarhwal",
"github_project": "elysia",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "elysia"
}
JSON
