- 
-
+
+`dataclassish.replace` is a one-liner that can work on any object (if it has a
+registered means to do so), regardless of mutability or nesting. Consider this
+fully immutable structure:
-p = Collection(Object(1.0, 2.0), Object(3.0, 4.0))
-print(p)
+```pycon
+>>> @dataclass(frozen=True)
+... class Object:
+... x: float | dict
+... y: float
+
+
+>>> @dataclass(frozen=True)
+... class Collection:
+... a: Object
+... b: Object
+
+
+>>> p = Collection(Object(1.0, 2.0), Object(3.0, 4.0))
+>>> p
Collection(a=Object(x=1.0, y=2.0), b=Object(x=3.0, y=4.0))
-replace(p, {"a": {"x": 5.0}, "b": {"y": 6.0}})
-# Collection(a=Object(x=5.0, y=2.0), b=Object(x=3.0, y=6.0))
+>>> replace(p, {"a": {"x": 5.0}, "b": {"y": 6.0}})
+Collection(a=Object(x=5.0, y=2.0), b=Object(x=3.0, y=6.0))
+
```
With `replace` this remains a one-liner. Replace pieces of any structure,
@@ -191,12 +253,13 @@ regardless of nesting.
To disambiguate dictionary fields from nested structures, use the `F` marker.
-```python
-from dataclassish import F
+```pycon
+>>> from dataclassish import F
+
+>>> replace(p, {"a": {"x": F({"thing": 5.0})}})
+Collection(a=Object(x={'thing': 5.0}, y=2.0),
+ b=Object(x=3.0, y=4.0))
-replace(p, {"a": {"x": F({"thing": 5.0})}})
-# Collection(a=Object(x={'thing': 5.0}, y=2.0),
-# b=Object(x=3.0, y=4.0))
```
### dataclass tools
@@ -205,78 +268,157 @@ replace(p, {"a": {"x": F({"thing": 5.0})}})
`replace`: `fields`, `asdict`, and `astuple`. `dataclassish` supports of all
these functions.
-```python
-from dataclassish import fields, asdict, astuple
+```pycon
+>>> from dataclassish import fields, asdict, astuple
-p = Point(1.0, 2.0)
+>>> p = Point(1.0, 2.0)
-print(fields(p))
-# (Field(name='x',...), Field(name='y',...))
+>>> fields(p)
+(Field(name='x',...), Field(name='y',...))
-print(asdict(p))
-# {'x': 1.0, 'y': 2.0}
+>>> asdict(p)
+{'x': 1.0, 'y': 2.0}
+
+>>> astuple(p)
+(1.0, 2.0)
-print(astuple(p))
-# (1.0, 2.0)
```
`dataclassish` extends these functions to [`dict`][dict-link]'s:
-```python
-p = {"x": 1, "y": 2.0}
+```pycon
+>>> p = {"x": 1, "y": 2.0}
+
+>>> fields(p)
+(Field(name='x',...), Field(name='y',...))
-print(fields(p))
-# (Field(name='x',...), Field(name='y',...))
+>>> asdict(p)
+{'x': 1, 'y': 2.0}
-print(asdict(p))
-# {'x': 1.0, 'y': 2.0}
+>>> astuple(p)
+(1, 2.0)
-print(astuple(p))
-# (1.0, 2.0)
```
Support for custom objects can be implemented similarly to `replace`.
-### converters
+### More tools
+
+In addition to the `dataclasses` tools, `dataclassish` provides a few more
+utilities.
+
+- `get_field` returns the field of an object by name.
+- `field_keys` returns the names of an object's fields.
+- `field_values` returns the values of an object's fields.
+- `field_items` returns the names and values of an object's fields.
+
+```pycon
+>>> from dataclassish import get_field, field_keys, field_values, field_items
+
+>>> p = Point(1.0, 2.0)
+
+>>> get_field(p, "x")
+1.0
+
+>>> field_keys(p)
+('x', 'y')
+
+>>> field_values(p)
+(1.0, 2.0)
+
+>>> field_items(p)
+(('x', 1.0), ('y', 2.0))
+
+```
+
+These functions work on any object that has been registered in, not just
+`@dataclass` objects.
+
+```pycon
+>>> p = {"x": 1, "y": 2.0}
+
+>>> get_field(p, "x")
+1
+
+>>> field_keys(p)
+dict_keys(['x', 'y'])
+
+>>> field_values(p)
+dict_values([1, 2.0])
+
+>>> field_items(p)
+dict_items([('x', 1), ('y', 2.0)])
+
+```
+
+### Converters
While `dataclasses.field` itself does not allow for converters (See PEP 712)
many dataclasses-like libraries do. A very short, very non-exhaustive list
includes: `attrs` and `equinox`. The module `dataclassish.converters` provides a
few useful converter functions. If you need more, check out `attrs`!
-```python
-from attrs import define, field
-from dataclassish.converters import Optional, Unless
+```pycon
+>>> from attrs import define, field
+>>> from dataclassish.converters import Optional, Unless
+
+
+>>> @define
+... class Class1:
+... attr: int | None = field(default=None, converter=Optional(int))
+... """attr is converted to an int or kept as None."""
-@define
-class Class1:
- attr: int | None = field(default=None, converter=Optional(int))
- """attr is converted to an int or kept as None."""
+>>> obj = Class1()
+>>> print(obj.attr)
+None
+>>> obj = Class1(attr=1.0)
+>>> obj.attr
+1
-obj = Class1()
-print(obj.attr)
-# None
+>>> @define
+... class Class2:
+... attr: float | int = field(converter=Unless(int, converter=float))
+... """attr is converted to a float, unless it's an int."""
-obj = Class1(a=1.0)
-print(obj.attr)
-# 1
+>>> obj = Class2(1)
+>>> obj.attr
+1
+>>> obj = Class2("1")
+>>> obj.attr
+1.0
+
+```
+
+### Flags
+
+`dataclassish` provides flags for customizing the behavior of functions. For
+example, the [`coordinax`](https://pypi.org/project/coordinax/) package, which
+depends on `dataclassish`, uses a flag `AttrFilter` to filter out fields from
+consideration by the functions in `dataclassish`.
+
+`dataclassish` provides a few built-in flags and flag-related utilities.
+
+```pycon
+>>> from dataclassish import flags
+>>> flags.__all__
+['FlagConstructionError', 'AbstractFlag', 'NoFlag']
+
+```
-@define
-class Class2:
- attr: float | int = field(converter=Unless(int, converter=float))
- """attr is converted to a float, unless it's an int."""
+Where `AbstractFlag` is the base class for flags, and `NoFlag` is a flag that
+does nothing. `FlagConstructionError` is an error that is raised when a flag is
+constructed incorrectly.
+As a quick example, we'll show how to use `NoFlag`.
-obj = Class2(1)
-print(obj.attr)
-# 1
+```pycon
+>>> from dataclassish import field_keys
+>>> tuple(field_keys(flags.NoFlag, p))
+('x', 'y')
-obj = Class2("1")
-print(obj.attr)
-# 1.0
```
## Citation
@@ -289,7 +431,6 @@ then click the link above.
## Development
[![Actions Status][actions-badge]][actions-link]
-[![Documentation Status][rtd-badge]][rtd-link]
[![codecov][codecov-badge]][codecov-link]
[![SPEC 0 — Minimum Supported Dependencies][spec0-badge]][spec0-link]
[![pre-commit][pre-commit-badge]][pre-commit-link]
diff --git a/conftest.py b/conftest.py
index 8af1483..75a7fb4 100644
--- a/conftest.py
+++ b/conftest.py
@@ -5,23 +5,30 @@
from sybil import Document, Region, Sybil
from sybil.parsers.myst import (
- DocTestDirectiveParser as MarkdownDocTestDirectiveParser,
- PythonCodeBlockParser as MarkdownPythonCodeBlockParser,
- SkipParser as MarkdownSkipParser,
+ DocTestDirectiveParser as MystDocTestDirectiveParser,
+ PythonCodeBlockParser as MystPythonCodeBlockParser,
+ SkipParser as MystSkipParser,
)
from sybil.parsers.rest import DocTestParser as ReSTDocTestParser
+from sybil.sybil import SybilCollection
optionflags = ELLIPSIS | NORMALIZE_WHITESPACE
parsers: Sequence[Callable[[Document], Iterable[Region]]] = [
- MarkdownDocTestDirectiveParser(optionflags=optionflags),
- MarkdownPythonCodeBlockParser(doctest_optionflags=optionflags),
- MarkdownSkipParser(),
+ MystDocTestDirectiveParser(optionflags=optionflags),
+ MystPythonCodeBlockParser(doctest_optionflags=optionflags),
+ MystSkipParser(),
]
+# TODO: figure out native parser for `pycon` that doesn't require a new line at
+# the end.
+readme = Sybil(
+ parsers=[ReSTDocTestParser(optionflags=optionflags)],
+ patterns=["README.md"],
+)
docs = Sybil(parsers=parsers, patterns=["*.md"])
python = Sybil(
parsers=[ReSTDocTestParser(optionflags=optionflags), *parsers], patterns=["*.py"]
)
-pytest_collect_file = (docs + python).pytest()
+pytest_collect_file = SybilCollection([docs, readme, python]).pytest()
diff --git a/pyproject.toml b/pyproject.toml
index b6fd29a..a4e9649 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -72,7 +72,7 @@ filterwarnings = [
]
log_cli_level = "INFO"
testpaths = [
- "src", "tests",
+ "README.md", "src", "tests",
]
Expand for detailed example
+
+This is a bad approach, updating the frozen dataclasses in place:
+
+```pycon
+>>> from copy import deepcopy
+
+>>> newp = deepcopy(p)
+>>> object.__setattr__(newp["a"], "x", 1.5)
+>>> object.__setattr__(newp["b"], "y", 4.5)
+>>> object.__setattr__(newp["c"], "x", 5.5)
-newp = deepcopy(p)
-newp["a"]["a1"] = 1.5
-newp["b"]["b2"] = 4.5
-newp["c"]["c1"] = 5.5
```
-And this is the simplest case, where the mutability of a [`dict`][dict-link]
-allows us to copy the full object and update it after. Note that we had to use
-[`deepcopy`](https://docs.python.org/3/library/copy.html#copy.deepcopy) to avoid
-mutating the sub-dicts. So what if the objects are immutable?
+A better way might be to create an entirely new object!
-```python
-@dataclass(frozen=True)
-class Object:
- x: float | dict
- y: float
+```pycon
+>>> newp = {"a": Point(1.5, p["a"].y),
+... "b": Point(p["b"].x, 4.5),
+... "c": Point(5.5, p["c"].y)}
+
+```
+This isn't so good either.
-@dataclass(frozen=True)
-class Collection:
- a: Object
- b: Object
+