From 5212fa03fdbffb6be1d11e0633ba0d8a18c6a426 Mon Sep 17 00:00:00 2001 From: Vincent Leroy Date: Wed, 28 Aug 2024 23:43:15 +0200 Subject: [PATCH] Cleanup documentation --- docs/index.rst | 18 +++++------------- docs/rst/api.rst | 9 --------- docs/rst/usage.rst | 16 ++++++++-------- src/dessinemoi/_core.py | 8 +++++++- 4 files changed, 20 insertions(+), 31 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 1e2191c..9f8827b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,3 @@ -.. dessinemoi documentation master file, created by - sphinx-quickstart on Tue May 25 18:21:12 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - :hide-toc: Dessine-moi @@ -22,17 +17,14 @@ Dessine-moi .. image:: https://img.shields.io/readthedocs/dessinemoi :target: https://dessinemoi.readthedocs.io -.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/mitsuhiko/rye/main/artwork/badge.json - :target: https://rye-up.com +.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/rye/main/artwork/badge.json + :target: https://rye.astral.sh :alt: Rye .. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json :target: https://github.com/astral-sh/ruff :alt: Ruff -.. image:: https://img.shields.io/badge/code%20style-black-black - :target: https://github.com/psf/black - *S'il vous plaît, dessine-moi un mouton.* Motivation @@ -45,16 +37,16 @@ born from the need to create dynamically object trees from nested dictionaries Features -------- -- Create a ``Factory`` object and register types to it. +- Create a :class:`.Factory` object and register types to it. - Use dictionaries to create objects from the factory. -- Create ``attrs``-compatible converters to automatically convert dictionaries +- Create *attrs*-compatible converters to automatically convert dictionaries to instances of registered types. - Customise factories to your needs. Getting started --------------- -*Dessine-moi* requires Python 3.8+ and depends on ``attrs``. It is tested with +*Dessine-moi* requires Python 3.8+ and depends on *attrs*. It is tested with Pytest. Install from PyPI in your virtual environment: diff --git a/docs/rst/api.rst b/docs/rst/api.rst index 7f10907..8887b3b 100644 --- a/docs/rst/api.rst +++ b/docs/rst/api.rst @@ -3,20 +3,11 @@ API Reference ============= -``Factory`` ------------ - .. autoclass:: dessinemoi.Factory :members: -``FactoryRegistryEntry`` ------------------------- - .. autoclass:: dessinemoi.FactoryRegistryEntry :members: -``LazyType`` ------------- - .. autoclass:: dessinemoi.LazyType :members: diff --git a/docs/rst/usage.rst b/docs/rst/usage.rst index 14a9a39..16294f6 100644 --- a/docs/rst/usage.rst +++ b/docs/rst/usage.rst @@ -26,7 +26,7 @@ strings, to Python types. Our factory has currently an empty registry: Register types to the factory ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Let's define a new Python type. For convenience, we will work with the ``attrs`` +Let's define a new Python type. For convenience, we will work with the *attrs* library, but *Dessine-moi* does not require you to use it. Let's define a simple class: @@ -102,9 +102,9 @@ keyword argument. Instantiate registered types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Once a type is registered, it can be instantiated using the :meth:`~.Factory.new` -method. If constructed class's constructor expects arguments, the ``args`` and -``kwargs`` arguments will forward them appropriately: +Once a type is registered, it can be instantiated using the +:meth:`~.Factory.create` method. If the constructed class's constructor expects +arguments, the ``args`` and ``kwargs`` arguments will forward them appropriately: .. doctest:: @@ -162,13 +162,13 @@ Convert objects ^^^^^^^^^^^^^^^ *Dessine-moi*'s factories implement converters which can be used as part of the -``attrs`` conversion step. In its most straightforward form, the +*attrs* conversion step. In its most straightforward form, the :meth:`~.Factory.convert` method operates on a ``value`` argument. * If ``value`` is not a dictionary, :meth:`~.Factory.convert` returns it unchanged. * If ``value`` is a dictionary, :meth:`~.Factory.convert` queries its ``type`` - entry for a type ID and uses it to call :meth:`~.Factory.new`. + entry for a type ID and uses it to call :meth:`~.Factory.create`. .. doctest:: @@ -179,7 +179,7 @@ Convert objects :class: note * :meth:`~.Factory.convert` takes a ``allowed_cls`` argument and uses it - exactly as :meth:`~.Factory.new` does. + exactly as :meth:`~.Factory.create` does. * Dictionary conversion won't work with classes expected non kw-only fields. * If a ``dict_constructor`` is associated to the registered type, it will be used to create the object instead of the default constructor. @@ -232,7 +232,7 @@ simply referenced by a :class:`.LazyType` instance. >>> factory.registry {'datetime': FactoryRegistryEntry(cls=LazyType(mod='datetime', attr='datetime'), dict_constructor=None)} -If we call :meth:`Factory.create`, the target type is imported and returned: +If we call :meth:`.Factory.create`, the target type is imported and returned: .. doctest:: diff --git a/src/dessinemoi/_core.py b/src/dessinemoi/_core.py index 21c8175..3db42dc 100644 --- a/src/dessinemoi/_core.py +++ b/src/dessinemoi/_core.py @@ -310,8 +310,14 @@ def alias(self, type_id: str, alias_id: str, overwrite_id: bool = False) -> None :param alias_id: Created alias ID. - :raises ValueError: + :param overwrite_id: + If ``True`` and ``alias_id`` is already registered, the existing + alias is redefined; else, a :class:`.ValueError` is raised. + :raises ValueError: + If the new alias cannot be registered, either because the target + type is not registered, or because the alias exists and is protected + against overwrites. .. versionadded:: 22.2.0 """