{"id":20603535,"url":"https://github.com/galacticdynamics/dataclassish","last_synced_at":"2025-04-15T02:06:59.068Z","repository":{"id":248807021,"uuid":"829828449","full_name":"GalacticDynamics/dataclassish","owner":"GalacticDynamics","description":"tools from `dataclasses`, extended to all of Python","archived":false,"fork":false,"pushed_at":"2025-04-09T01:08:58.000Z","size":136,"stargazers_count":3,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-15T02:06:48.587Z","etag":null,"topics":["dataclasses-python"],"latest_commit_sha":null,"homepage":"https://zenodo.org/doi/10.5281/zenodo.13357978","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GalacticDynamics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-17T04:44:50.000Z","updated_at":"2025-04-09T01:09:02.000Z","dependencies_parsed_at":"2024-08-26T19:34:12.725Z","dependency_job_id":"d24a2b02-ea38-4553-ac67-ac69c3f5e3d9","html_url":"https://github.com/GalacticDynamics/dataclassish","commit_stats":null,"previous_names":["galacticdynamics/dataclasstools","galacticdynamics/dataclassish"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GalacticDynamics%2Fdataclassish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GalacticDynamics%2Fdataclassish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GalacticDynamics%2Fdataclassish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GalacticDynamics%2Fdataclassish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GalacticDynamics","download_url":"https://codeload.github.com/GalacticDynamics/dataclassish/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991543,"owners_count":21194894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dataclasses-python"],"created_at":"2024-11-16T09:17:43.172Z","updated_at":"2025-04-15T02:06:59.060Z","avatar_url":"https://github.com/GalacticDynamics.png","language":"Python","readme":"\u003ch1 align='center'\u003e dataclassish \u003c/h1\u003e\n\u003ch3 align=\"center\"\u003eTools from \u003ccode\u003edataclasses\u003c/code\u003e, extended to all of Python\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://pypi.org/project/dataclassish/\"\u003e \u003cimg alt=\"PyPI: dataclassish\" src=\"https://img.shields.io/pypi/v/dataclassish?style=flat\" /\u003e \u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/dataclassish/\"\u003e \u003cimg alt=\"PyPI versions: dataclassish\" src=\"https://img.shields.io/pypi/pyversions/dataclassish\" /\u003e \u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/dataclassish/\"\u003e \u003cimg alt=\"dataclassish license\" src=\"https://img.shields.io/github/license/GalacticDynamics/dataclassish\" /\u003e \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/GalacticDynamics/dataclassish/actions\"\u003e \u003cimg alt=\"CI status\" src=\"https://github.com/GalacticDynamics/dataclassish/workflows/CI/badge.svg\" /\u003e \u003c/a\u003e\n    \u003ca href=\"https://codecov.io/gh/GalacticDynamics/dataclassish\"\u003e \u003cimg alt=\"codecov\" src=\"https://codecov.io/gh/GalacticDynamics/dataclassish/graph/badge.svg\" /\u003e \u003c/a\u003e\n    \u003ca href=\"https://scientific-python.org/specs/spec-0000/\"\u003e \u003cimg alt=\"ruff\" src=\"https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811\u0026color=%235CA038\" /\u003e \u003c/a\u003e\n    \u003ca href=\"https://docs.astral.sh/ruff/\"\u003e \u003cimg alt=\"ruff\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\" /\u003e \u003c/a\u003e\n    \u003ca href=\"https://pre-commit.com\"\u003e \u003cimg alt=\"pre-commit\" src=\"https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\" /\u003e \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nPython's [`dataclasses`][dataclasses-link] provides tools for working with\nobjects, but only compatible `@dataclass` objects. 😢 \u003c/br\u003e This repository is a\nsuperset of those tools and extends them to work on ANY Python object you want!\n🎉 \u003c/br\u003e You can easily register in object-specific methods and use a unified\ninterface for object manipulation. 🕶️\n\nFor example,\n\n```python\nfrom dataclassish import replace  # New object, replacing select fields\n\nd1 = {\"a\": 1, \"b\": 2.0, \"c\": \"3\"}\nd2 = replace(d1, c=3 + 0j)\nprint(d2)\n# {'a': 1, 'b': 2.0, 'c': (3+0j)}\n```\n\n## Installation\n\n[![PyPI platforms][pypi-platforms]][pypi-link]\n[![PyPI version][pypi-version]][pypi-link]\n\n```bash\npip install dataclassish\n```\n\n## Documentation\n\n- [Getting Started](#getting-started)\n  - [Replacing a `@dataclass`](#replacing-a-dataclass)\n  - [Replacing a `dict`](#replacing-a-dict)\n  - [Replacing via the `__replace__` Method](#replacing-via-the-__replace__-method)\n  - [Replacing a Custom Type](#replacing-a-custom-type)\n- [Nested Replacement](#nested-replacement)\n- [dataclass tools](#dataclass-tools)\n- [More tools](#more-tools)\n- [Converters](#converters)\n- [Flags](#flags)\n\n### Getting Started\n\n#### Replacing a `@dataclass`\n\nIn this example we'll show how `dataclassish` works exactly the same as\n[`dataclasses`][dataclasses-link] when working with a `@dataclass` object.\n\n```pycon\n\u003e\u003e\u003e from dataclassish import replace\n\u003e\u003e\u003e from dataclasses import dataclass\n\n\u003e\u003e\u003e @dataclass(frozen=True)\n... class Point:\n...     x: float | int\n...     y: float | int\n\n\n\u003e\u003e\u003e p = Point(1.0, 2.0)\n\u003e\u003e\u003e p\nPoint(x=1.0, y=2.0)\n\n\u003e\u003e\u003e p2 = replace(p, x=3.0)\n\u003e\u003e\u003e p2\nPoint(x=3.0, y=2.0)\n\n```\n\n#### Replacing a `dict`\n\nNow we'll work with a [`dict`][dict-link] object. Note that\n[`dataclasses`][dataclasses-link] does _not_ work with [`dict`][dict-link]\nobjects, but with `dataclassish` it's easy!\n\n```pycon\n\u003e\u003e\u003e from dataclassish import replace\n\n\u003e\u003e\u003e p = {\"x\": 1, \"y\": 2.0}\n\u003e\u003e\u003e p\n{'x': 1, 'y': 2.0}\n\n\u003e\u003e\u003e p2 = replace(p, x=3.0)\n\u003e\u003e\u003e p2\n{'x': 3.0, 'y': 2.0}\n\n# If we try to `replace` a value that isn't in the dict, we'll get an error\n\u003e\u003e\u003e try:\n...     replace(p, z=None)\n... except ValueError as e:\n...     print(e)\ninvalid keys {'z'}.\n\n```\n\n#### Replacing via the `__replace__` Method\n\nIn Python 3.13+ objects can implement the `__replace__` method to define how\n`copy.replace` should operate on them. This was directly inspired by\n`dataclass.replace`, and is a nice generalization to more general Python\nobjects. `dataclassish` too supports this method.\n\n```pycon\n\u003e\u003e\u003e class HasReplace:\n...     def __init__(self, a, b):\n...         self.a = a\n...         self.b = b\n...     def __repr__(self) -\u003e str:\n...         return f\"HasReplace(a={self.a},b={self.b})\"\n...     def __replace__(self, **changes):\n...         return type(self)(**(self.__dict__ | changes))\n\n\u003e\u003e\u003e obj = HasReplace(1, 2)\n\u003e\u003e\u003e obj\nHasReplace(a=1,b=2)\n\n\u003e\u003e\u003e obj2 = replace(obj, b=3)\n\u003e\u003e\u003e obj2\nHasReplace(a=1,b=3)\n\n```\n\n#### Replacing a Custom Type\n\nLet's say there's a custom object that we want to use `replace` on, but which\ndoesn't have a `__replace__` method (or which we want more control over using a\nsecond argument, discussed later). Registering in a custom type is very easy!\nLet's make a custom object and define how `replace` will operate on it.\n\n```pycon\n\u003e\u003e\u003e from typing import Any\n\u003e\u003e\u003e from plum import dispatch\n\n\u003e\u003e\u003e class MyClass:\n...     def __init__(self, a, b, c):\n...         self.a = a\n...         self.b = b\n...         self.c = c\n...     def __repr__(self) -\u003e str:\n...         return f\"MyClass(a={self.a},b={self.b},c={self.c})\"\n\n\n\u003e\u003e\u003e @dispatch\n... def replace(obj: MyClass, **changes: Any) -\u003e MyClass:\n...     current_args = {k: getattr(obj, k) for k in \"abc\"}\n...     updated_args = current_args | changes\n...     return MyClass(**updated_args)\n\n\n\u003e\u003e\u003e obj = MyClass(1, 2, 3)\n\u003e\u003e\u003e obj\nMyClass(a=1,b=2,c=3)\n\n\u003e\u003e\u003e obj2 = replace(obj, c=4.0)\n\u003e\u003e\u003e obj2\nMyClass(a=1,b=2,c=4.0)\n\n```\n\n### Nested Replacement\n\n`replace` can also accept a second positional argument which is a dictionary\nspecifying a nested replacement. For example consider the following dict of\nPoint objects:\n\n```pycon\n\u003e\u003e\u003e p = {\"a\": Point(1, 2), \"b\": Point(3, 4), \"c\": Point(5, 6)}\n\n```\n\nWith `replace` the nested structure can be updated via:\n\n```pycon\n\u003e\u003e\u003e replace(p, {\"a\": {\"x\": 1.5}, \"b\": {\"y\": 4.5}, \"c\": {\"x\": 5.5}})\n{'a': Point(x=1.5, y=2), 'b': Point(x=3, y=4.5), 'c': Point(x=5.5, y=6)}\n\n```\n\nIn contrast in pure Python this would be very challenging. Expand the example\nbelow to see how this might be done.\n\n\u003cdetails\u003e\n\u003csummary\u003eExpand for detailed example\u003c/summary\u003e\n\nThis is a bad approach, updating the frozen dataclasses in place:\n\n```pycon\n\u003e\u003e\u003e from copy import deepcopy\n\n\u003e\u003e\u003e newp = deepcopy(p)\n\u003e\u003e\u003e object.__setattr__(newp[\"a\"], \"x\", 1.5)\n\u003e\u003e\u003e object.__setattr__(newp[\"b\"], \"y\", 4.5)\n\u003e\u003e\u003e object.__setattr__(newp[\"c\"], \"x\", 5.5)\n\n```\n\nA better way might be to create an entirely new object!\n\n```pycon\n\u003e\u003e\u003e newp = {\"a\": Point(1.5, p[\"a\"].y),\n...         \"b\": Point(p[\"b\"].x, 4.5),\n...         \"c\": Point(5.5, p[\"c\"].y)}\n\n```\n\nThis isn't so good either.\n\n\u003c/details\u003e\n\n`dataclassish.replace` is a one-liner that can work on any object (if it has a\nregistered means to do so), regardless of mutability or nesting. Consider this\nfully immutable structure:\n\n```pycon\n\u003e\u003e\u003e @dataclass(frozen=True)\n... class Object:\n...     x: float | dict\n...     y: float\n\n\n\u003e\u003e\u003e @dataclass(frozen=True)\n... class Collection:\n...     a: Object\n...     b: Object\n\n\n\u003e\u003e\u003e p = Collection(Object(1.0, 2.0), Object(3.0, 4.0))\n\u003e\u003e\u003e p\nCollection(a=Object(x=1.0, y=2.0), b=Object(x=3.0, y=4.0))\n\n\u003e\u003e\u003e replace(p, {\"a\": {\"x\": 5.0}, \"b\": {\"y\": 6.0}})\nCollection(a=Object(x=5.0, y=2.0), b=Object(x=3.0, y=6.0))\n\n```\n\nWith `replace` this remains a one-liner. Replace pieces of any structure,\nregardless of nesting.\n\nTo disambiguate dictionary fields from nested structures, use the `F` marker.\n\n```pycon\n\u003e\u003e\u003e from dataclassish import F\n\n\u003e\u003e\u003e replace(p, {\"a\": {\"x\": F({\"thing\": 5.0})}})\nCollection(a=Object(x={'thing': 5.0}, y=2.0),\n           b=Object(x=3.0, y=4.0))\n\n```\n\n### dataclass tools\n\n[`dataclasses`][dataclasses-link] has a number of utility functions beyond\n`replace`: `fields`, `asdict`, and `astuple`. `dataclassish` supports of all\nthese functions.\n\n```pycon\n\u003e\u003e\u003e from dataclassish import fields, asdict, astuple\n\n\u003e\u003e\u003e p = Point(1.0, 2.0)\n\n\u003e\u003e\u003e fields(p)\n(Field(name='x',...), Field(name='y',...))\n\n\u003e\u003e\u003e asdict(p)\n{'x': 1.0, 'y': 2.0}\n\n\u003e\u003e\u003e astuple(p)\n(1.0, 2.0)\n\n```\n\n`dataclassish` extends these functions to [`dict`][dict-link]'s:\n\n```pycon\n\u003e\u003e\u003e p = {\"x\": 1, \"y\": 2.0}\n\n\u003e\u003e\u003e fields(p)\n(Field(name='x',...), Field(name='y',...))\n\n\u003e\u003e\u003e asdict(p)\n{'x': 1, 'y': 2.0}\n\n\u003e\u003e\u003e astuple(p)\n(1, 2.0)\n\n```\n\nSupport for custom objects can be implemented similarly to `replace`.\n\n### More tools\n\nIn addition to the `dataclasses` tools, `dataclassish` provides a few more\nutilities.\n\n- `get_field` returns the field of an object by name.\n- `field_keys` returns the names of an object's fields.\n- `field_values` returns the values of an object's fields.\n- `field_items` returns the names and values of an object's fields.\n\n```pycon\n\u003e\u003e\u003e from dataclassish import get_field, field_keys, field_values, field_items\n\n\u003e\u003e\u003e p = Point(1.0, 2.0)\n\n\u003e\u003e\u003e get_field(p, \"x\")\n1.0\n\n\u003e\u003e\u003e field_keys(p)\n('x', 'y')\n\n\u003e\u003e\u003e field_values(p)\n(1.0, 2.0)\n\n\u003e\u003e\u003e field_items(p)\n(('x', 1.0), ('y', 2.0))\n\n```\n\nThese functions work on any object that has been registered in, not just\n`@dataclass` objects.\n\n```pycon\n\u003e\u003e\u003e p = {\"x\": 1, \"y\": 2.0}\n\n\u003e\u003e\u003e get_field(p, \"x\")\n1\n\n\u003e\u003e\u003e field_keys(p)\ndict_keys(['x', 'y'])\n\n\u003e\u003e\u003e field_values(p)\ndict_values([1, 2.0])\n\n\u003e\u003e\u003e field_items(p)\ndict_items([('x', 1), ('y', 2.0)])\n\n```\n\n### Converters\n\nWhile `dataclasses.field` itself does not allow for converters (See PEP 712)\nmany dataclasses-like libraries do. A very short, very non-exhaustive list\nincludes: `attrs` and `equinox`. The module `dataclassish.converters` provides a\nfew useful converter functions. If you need more, check out `attrs`!\n\n```pycon\n\u003e\u003e\u003e from attrs import define, field\n\u003e\u003e\u003e from dataclassish.converters import Optional, Unless\n\n\n\u003e\u003e\u003e @define\n... class Class1:\n...     attr: int | None = field(default=None, converter=Optional(int))\n...     \"\"\"attr is converted to an int or kept as None.\"\"\"\n\n\n\u003e\u003e\u003e obj = Class1()\n\u003e\u003e\u003e print(obj.attr)\nNone\n\n\u003e\u003e\u003e obj = Class1(attr=1.0)\n\u003e\u003e\u003e obj.attr\n1\n\n\u003e\u003e\u003e @define\n... class Class2:\n...     attr: float | int = field(converter=Unless(int, converter=float))\n...     \"\"\"attr is converted to a float, unless it's an int.\"\"\"\n\n\u003e\u003e\u003e obj = Class2(1)\n\u003e\u003e\u003e obj.attr\n1\n\n\u003e\u003e\u003e obj = Class2(\"1\")\n\u003e\u003e\u003e obj.attr\n1.0\n\n```\n\nThis library also provide a lightweight dataclass-like decorator and field\nfunction that supports these converters and converters in general.\n\n```pycon\n\u003e\u003e\u003e from dataclassish.converters import dataclass, field\n\n\u003e\u003e\u003e @dataclass\n... class MyClass:\n...     a: int | None = field(converter=Optional(int))\n...     b: str = field(converter=str.upper)\n\n\u003e\u003e\u003e obj = MyClass(a=\"1\", b=\"hello\")\n\u003e\u003e\u003e obj\nMyClass(a=1, b='HELLO')\n\n\u003e\u003e\u003e obj = MyClass(a=None, b=\"there\")\n\u003e\u003e\u003e obj\nMyClass(a=None, b='THERE')\n\n```\n\n### Flags\n\n`dataclassish` provides flags for customizing the behavior of functions. For\nexample, the [`coordinax`](https://pypi.org/project/coordinax/) package, which\ndepends on `dataclassish`, uses a flag `AttrFilter` to filter out fields from\nconsideration by the functions in `dataclassish`.\n\n`dataclassish` provides a few built-in flags and flag-related utilities.\n\n```pycon\n\u003e\u003e\u003e from dataclassish import flags\n\u003e\u003e\u003e flags.__all__\n['FlagConstructionError', 'AbstractFlag', 'NoFlag', 'FilterRepr']\n\n```\n\nWhere `AbstractFlag` is the base class for flags, `NoFlag` is a flag that does\nnothing, and `FilterRepr` will filter out any fields with `repr=True`.\n`FlagConstructionError` is an error that is raised when a flag is constructed\nincorrectly.\n\nAs a quick example, we'll show how to use `NoFlag`.\n\n```pycon\n\u003e\u003e\u003e from dataclassish import field_keys\n\u003e\u003e\u003e tuple(field_keys(flags.NoFlag, p))\n('x', 'y')\n\n```\n\nAs another example, we'll show how to use `FilterRepr`.\n\n```pycon\n\u003e\u003e\u003e from dataclasses import field\n\u003e\u003e\u003e @dataclass\n... class Point:\n...     x: float\n...     y: float = field(repr=False)\n\u003e\u003e\u003e obj = Point(1.0, 2.0)\n\n\u003e\u003e\u003e field_keys(flags.FilterRepr, obj)\n('x',)\n\n```\n\n## Citation\n\n[![DOI][zenodo-badge]][zenodo-link]\n\nIf you enjoyed using this library and would like to cite the software you use\nthen click the link above.\n\n## Development\n\n[![Actions Status][actions-badge]][actions-link]\n[![codecov][codecov-badge]][codecov-link]\n[![SPEC 0 — Minimum Supported Dependencies][spec0-badge]][spec0-link]\n[![pre-commit][pre-commit-badge]][pre-commit-link]\n[![ruff][ruff-badge]][ruff-link]\n\nWe welcome contributions!\n\n\u003c!-- prettier-ignore-start --\u003e\n[actions-badge]:            https://github.com/GalacticDynamics/dataclassish/workflows/CI/badge.svg\n[actions-link]:             https://github.com/GalacticDynamics/dataclassish/actions\n[codecov-badge]:            https://codecov.io/gh/GalacticDynamics/dataclassish/graph/badge.svg\n[codecov-link]:             https://codecov.io/gh/GalacticDynamics/dataclassish\n[pre-commit-badge]:         https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\n[pre-commit-link]:          https://pre-commit.com\n[pypi-link]:                https://pypi.org/project/dataclassish/\n[pypi-platforms]:           https://img.shields.io/pypi/pyversions/dataclassish\n[pypi-version]:             https://img.shields.io/pypi/v/dataclassish\n[ruff-badge]:               https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\n[ruff-link]:                https://docs.astral.sh/ruff/\n[spec0-badge]:              https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811\u0026color=%235CA038\n[spec0-link]:               https://scientific-python.org/specs/spec-0000/\n[zenodo-badge]:             https://zenodo.org/badge/DOI/10.5281/zenodo.13357978.svg\n[zenodo-link]:              https://zenodo.org/doi/10.5281/zenodo.13357978\n\n\n[dataclasses-link]: https://docs.python.org/3/library/dataclasses.html\n[dict-link]: https://docs.python.org/3.8/library/stdtypes.html#dict\n\n\u003c!-- prettier-ignore-end --\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalacticdynamics%2Fdataclassish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgalacticdynamics%2Fdataclassish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalacticdynamics%2Fdataclassish/lists"}