init false initial work (#395)

* init false initial work

* Finish up init false

* Fix lint

HISTORY.md

@@ -2,6 +2,10 @@
 
 ## 23.2.0 (UNRELEASED)
 
+- **Potentially breaking**: skip _attrs_ fields marked as `init=False` by default. This change is potentially breaking for unstructuring.
+  See [here](https://catt.rs/en/latest/customizing.html#include_init_false) for instructions on how to restore the old behavior.
+  ([#40](https://github.com/python-attrs/cattrs/issues/40) [#395](https://github.com/python-attrs/cattrs/pull/395))
+- The `omit` parameter of `cattrs.override()` is now of type `bool | None` (from `bool`). `None` is the new default and means to apply default `cattrs` handling to the attribute.
 - Fix `format_exception` parameter working for recursive calls to `transform_error`
   ([#389](https://github.com/python-attrs/cattrs/issues/389)
 - [_attrs_ aliases](https://www.attrs.org/en/stable/init.html#private-attributes-and-aliases) are now supported, although aliased fields still map to their attribute name instead of their alias by default when un/structuring.
@@ -42,7 +46,7 @@
   ([#319](https://github.com/python-attrs/cattrs/issues/319) [#327](https://github.com/python-attrs/cattrs/pull/327>))
 - `pathlib.Path` is now supported by default.
   ([#81](https://github.com/python-attrs/cattrs/issues/81))
-- Add `cbor2` serialization library to the `cattr.preconf` package.
+- Add `cbor2` serialization library to the `cattrs.preconf` package.
 - Add optional dependencies for `cattrs.preconf` third-party libraries. ([#337](https://github.com/python-attrs/cattrs/pull/337))
 - All preconf converters now allow overriding the default `unstruct_collection_overrides` in `make_converter`.
   ([#350](https://github.com/python-attrs/cattrs/issues/350) [#353](https://github.com/python-attrs/cattrs/pull/353))

Makefile

@@ -1,4 +1,4 @@
-.PHONY: clean clean-test clean-pyc clean-build docs help bench bench-cmp
+.PHONY: clean clean-test clean-pyc clean-build docs help bench bench-cmp test
 .DEFAULT_GOAL := help
 define BROWSER_PYSCRIPT
 import os, webbrowser, sys

README.md

@@ -141,7 +141,7 @@ destructure them.
   - Custom converters for any type can be registered using `register_structure_hook`.
 
 _cattrs_ comes with preconfigured converters for a number of serialization libraries, including json, msgpack, cbor2, bson, yaml and toml.
-For details, see the [cattr.preconf package](https://catt.rs/en/stable/preconf.html).
+For details, see the [cattrs.preconf package](https://catt.rs/en/stable/preconf.html).
 
 ## Design Decisions
 

docs/Makefile

@@ -3,15 +3,10 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = pdm run sphinx-build
 PAPER         =
 BUILDDIR      = _build
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
@@ -177,4 +172,4 @@ pseudoxml:
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
 
 apidoc:
-	sphinx-apidoc -o . ../src/cattrs/ -f
+	pdm run sphinx-apidoc -o . ../src/cattrs/ -f

docs/converters.md

@@ -6,7 +6,7 @@ global converter. Changes done to this global converter, such as registering new
 structure and unstructure hooks, affect all code using the global
 functions.
 
-## Global converter
+## Global Converter
 
 A global converter is provided for convenience as `cattrs.global_converter`.
 The following functions implicitly use this global converter:
@@ -21,7 +21,7 @@ Changes made to the global converter will affect the behavior of these functions
 Larger applications are strongly encouraged to create and customize a different,
 private instance of {class}`cattrs.Converter`.
 
-## Converter objects
+## Converter Objects
 
 To create a private converter, simply instantiate a {class}`cattrs.Converter`.
 Currently, a converter contains the following state:

docs/customizing.md

@@ -13,7 +13,7 @@ them for types using {meth}`Converter.register_structure_hook() <cattrs.BaseConv
 {meth}`Converter.register_unstructure_hook() <cattrs.BaseConverter.register_unstructure_hook>`. This approach is the most
 flexible but also requires the most amount of boilerplate.
 
-## Using `cattrs.gen` generators
+## Using `cattrs.gen` Generators
 
 _cattrs_ includes a module, {mod}`cattrs.gen`, which allows for generating and compiling specialized functions for unstructuring _attrs_ classes.
 
@@ -25,9 +25,8 @@ Currently, the overrides only support generating dictionary un/structuring funct
 
 ### `omit_if_default`
 
-This override can be applied on a per-class or per-attribute basis. The generated
-unstructuring function will skip unstructuring values that are equal to their
-default or factory values.
+This override can be applied on a per-class or per-attribute basis.
+The generated unstructuring function will skip unstructuring values that are equal to their default or factory values.
 
 ```{doctest}
 
@@ -131,9 +130,8 @@ ExampleClass(klass=1)
 
 ### `omit`
 
-This override can only be applied to individual attributes. Using the `omit`
-override will simply skip the attribute completely when generating a structuring
-or unstructuring function.
+This override can only be applied to individual attributes. 
+Using the `omit` override will simply skip the attribute completely when generating a structuring or unstructuring function.
 
 ```{doctest}
 
@@ -198,3 +196,38 @@ AliasClass(number=2)
 ```{versionadded} 23.2.0
 
 ```
+
+### `include_init_false`
+
+By default, _attrs_ fields defined as `init=False` are skipped when un/structuring.
+By generating your un/structure function with `_cattrs_include_init_false=True`, all `init=False` fields will be included for un/structuring.
+
+```{doctest}
+
+>>> from cattrs.gen import make_dict_structure_fn
+>>>
+>>> @define
+... class ClassWithInitFalse:
+...    number: int = field(default=1, init=False)
+>>>
+>>> c = cattrs.Converter()
+>>> hook = make_dict_structure_fn(ClassWithInitFalse, c, _cattrs_include_init_false=True)
+>>> c.register_structure_hook(ClassWithInitFalse, hook)
+>>> c.structure({"number": 2}, ClassWithInitFalse)
+ClassWithInitFalse(number=2)
+```
+
+A single attribute can be included by overriding it with `omit=False`.
+
+```{doctest}
+
+>>> c = cattrs.Converter()
+>>> hook = make_dict_structure_fn(ClassWithInitFalse, c, number=override(omit=False))
+>>> c.register_structure_hook(ClassWithInitFalse, hook)
+>>> c.structure({"number": 2}, ClassWithInitFalse)
+ClassWithInitFalse(number=2)
+```
+
+```{versionadded} 23.2.0
+
+```