ready for 1.2.0 (#10)

* code is working

* doc done

* .

---------

Co-authored-by: Ben Avrahami <[email protected]>

CHANGELOG.md

@@ -1,7 +1,21 @@
 # envolved Changelog
-## Next
+## 1.2.0
+### Added
+* new argument `strip_items` for `CollectionParser`.
+* new arguments `strip_keys` and `strip_values` for `CollectionParser.pairwise_delimited`.
+* `missing`, `as_default`, `no_patch`, and `discard` consts are now available in the `envolved` namespace.
+* envvar descriptions can now also be a sequence of strings to denote multiple paragraphs.
+* many new options for describing env vars
+* inferred env vars can now be used for parameters that don't have a type hint, so long as the default and type are provided.
+### Fixed
+* the default `case_sensitive` value for `inferred_env_var`s is now `False` instead of `True`.
+* envvars create with `with_prefix` are now correctly added to the description
+* calling `describe_env_vars` without any envvars defined no longer raises an error
 ### Docs
 * changed documentation theme with furo
+### Deprecations
+* usage of the `basevar` and `infer_env_var` modules is deprecated
+* usage of the `envvar` function to create inferred envvars is deprecated
 ## 1.1.2
 ### Fixed
 * changed type of `args` to be an invariant `Mapping` instead of a `dict`

docs/constants.rst

@@ -3,27 +3,27 @@ Constants
 
 Runtime constants for the envolved library
 
-.. py:currentmodule:: basevar
+.. py:currentmodule:: envvar
 
 .. py:data:: missing
     :type: object
 
-    Used to indicate that an EnvVar has no default value. Can also be used in :attr:`~basevar.SchemaEnvVar.on_partial`
+    Used to indicate that an EnvVar has no default value. Can also be used in :attr:`~envvar.SchemaEnvVar.on_partial`
     to specify that an error should be raised on partial environments.
 
 .. py:data:: as_default
     :type: object
 
-    Used in :attr:`~basevar.SchemaEnvVar.on_partial` to specify that the default should be returned on partial
+    Used in :attr:`~envvar.SchemaEnvVar.on_partial` to specify that the default should be returned on partial
     environments.
 
 .. py:data:: no_patch
     :type: object
 
-    Used in :attr:`~basevar.EnvVar.monkeypatch` to specify that the EnvVar should not be patched.
+    Used in :attr:`~envvar.EnvVar.monkeypatch` to specify that the EnvVar should not be patched.
 
 .. py:data:: discard
     :type: object
 
-    When returned by child env vars of :class:`~basevar.SchemaEnvVar`, the value, and argument, will be discarded. If
+    When returned by child env vars of :class:`~envvar.SchemaEnvVar`, the value, and argument, will be discarded. If
     a positional argument returns this value, all positional arguments after it will also be discarded.

docs/cookbook.rst

@@ -31,7 +31,7 @@ external changes to environment variables are not handled.
 
 Common Factories
 -----------------
-Here are some common types and factories to use when creating a :class:`~basevar.SchemaEnvVar`
+Here are some common types and factories to use when creating a :class:`~envvar.SchemaEnvVar`
 
 * :class:`types.SimpleNamespace`: This will create a namespace with whatever arguments you pass to it.
 * :class:`typing.NamedTuple`: A quick and easy way to create an annotated named tuple.
@@ -64,4 +64,49 @@ Here are some common types and factories to use when creating a :class:`~basevar
         'y': inferred_env_var(),
     })
 
-    # this will result in a dict that has ints for keys "x" and "y"
+    # this will result in a dict that has ints for keys "x" and "y"
+
+Inferring Schema Parameter Names Without a Schema
+--------------------------------------------------
+
+We can actually use :func:`~envvar.inferred_env_var` to infer the name of :class:`~envvar.EnvVar` parameters without a schema. This is useful when
+we want to prototype a schema without having to create a schema class.
+
+.. code-block::
+    from envolved import ...
+    
+    my_schema_ev = env_var('FOO_', type=SimpleNamespace, args={
+        'x': inferred_env_var(type=int, default=0),
+        'y': inferred_env_var(type=string, default='hello'),
+    })
+
+    # this will result in a namespace that fills `x` and `y` with the values of `FOO_X` and `FOO_Y` respectively
+
+
+Note a sticking point here, he have to specify not only the type of the inferred env var, but also the default value.
+
+.. code-block::
+    from envolved import ...
+
+    my_schema_ev = env_var('FOO_', type=SimpleNamespace, args={
+        'x': inferred_env_var(type=int),  # <-- this code will raise an exception
+    })
+
+.. note:: Why is this the behaviour?
+
+    In normal :func:`~envvar.env_var`, not passing a `default` implies that the EnvVar is required, why can't we do the same for :func:`~envvar.inferred_env_var`? We do this to reduce side
+    effects when an actual schema is passed in. If we were to assume that the inferred env var is required, then plugging in a schema that has a default value for that parameter would be
+    a hard-to-detect breaking change that can have catostraphic consequences. By requiring the default value to be passed in, we force the user to be explicit about the default values,
+    ehan it might be inferred.
+
+We can specify that an inferred env var is required by explicitly stating `default=missing`
+
+.. code-block::
+    from envolved import ..., missing
+
+    my_schema_ev = env_var('FOO_', type=SimpleNamespace, args={
+        'x': inferred_env_var(type=int, default=missing),
+        'y': inferred_env_var(type=string, default='hello'),
+    })
+
+    # this will result in a namespace that fills `x` with the value of `FOO_X` and will raise an exception if `FOO_X` is not set

docs/describing.rst

@@ -14,7 +14,7 @@ Another feature of envolved is the ability to describe all EnvVars.
                                     'level': env_var('_LEVEL', type=int, default=20),
                                 })
 
-    print('\n'.describe_env_vars())
+    print('\n'.join(describe_env_vars()))
 
     # OUTPUT:
     # BACKLOG_SIZE: Backlog size
@@ -33,7 +33,7 @@ Another feature of envolved is the ability to describe all EnvVars.
 .. function:: describe_env_vars(**kwargs)->List[str]
 
     Returns a list of string lines that describe all the EnvVars. All keyword arguments are passed to
-    :class:`textwrap.wrap` to wrap the lines.
+    :func:`textwrap.wrap` to wrap the lines.
 
     .. note::
 
@@ -70,3 +70,49 @@ In some cases it is useful to exclude some EnvVars from the description. This ca
                      of EnvVar names to EnvVars.
     :return: `env_vars`, to allow for piping.
 
+.. class:: EnvVarsDescription(env_vars: collections.abc.Iterable[EnvVar] | None)
+
+    A class that allows for more fine-grained control over the description of EnvVars.
+
+    :param env_vars: A collection of EnvVars to describe. If None, all alive EnvVars will be described. If the collection
+                     includes two EnvVars, one which is a parent of the other, only the parent will be described.
+
+    .. method:: flat()->FlatEnvVarsDescription
+
+        Returns a flat description of the EnvVars. 
+
+    .. method:: nested()->NestedEnvVarsDescription
+
+        Returns a nested description of the EnvVars.
+
+.. class:: FlatEnvVarsDescription
+
+    A flat representation of the EnvVars description. Only single-environment variable EnvVars (or single-environment variable children of envars) will be described.
+
+    .. method:: wrap_sorted(*, unique_keys: bool = True, **kwargs)->List[str]
+
+        Returns a list of string lines that describe the EnvVars, sorted by their environment variable key.
+
+        :param unique_keys: If True, and if any EnvVars share an environment variable key, they will be combined into one description.
+        :param kwargs: Keyword arguments to pass to :func:`textwrap.wrap`.
+        :return: A list of string lines that describe the EnvVars.
+
+    .. method:: wrap_grouped(**kwargs)->List[str]
+
+        Returns a list of string lines that describe the EnvVars, sorted by their environment variable key, but env-vars that are used by the same schema will appear together.
+
+        :param kwargs: Keyword arguments to pass to :func:`textwrap.wrap`.
+        :return: A list of string lines that describe the EnvVars.
+
+.. class:: NestedEnvVarsDescription
+
+    A nested representation of the EnvVars description. All EnvVars will be described.
+
+    .. method:: wrap(indent_increment: str = ..., **kwargs)->List[str]
+
+        Returns a list of string lines that describe the EnvVars in a tree structure.
+
+        :param indent_increment: The string to use to increment the indentation of the description with each level. If not provided,
+         will use the keyword argument "subsequent_indent" from :func:`textwrap.wrap`, if provided. Otherwise, will use a single space.
+        :param kwargs: Keyword arguments to pass to :func:`textwrap.wrap`.
+        :return: A list of string lines that describe the EnvVars.