pythonic-fp.containers 4.0.1__tar.gz → 4.1.0__tar.gz

pythonic_fp_containers-4.1.0/.github/workflows/static.yml

@@ -0,0 +1,64 @@
+name: Build and Deploy Furo Themed Sphinx Documentation
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+env:
+  RELEASE: '4.1.0'
+  DEVEL: '5.0.0'
+  PYTHON: '3.14'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Select Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON }}
+
+      - name: Install Sphinx Dependencies
+        run: |
+          pip install -r docs/requirements.txt
+          sudo apt-get install -y graphviz
+
+      - name: Build Release Docs
+        run: |
+          pip install pythonic-fp-circulararray
+          docs/gen_conf.py release ${{ env.RELEASE }} Containers containers > docs/source/conf.py
+          sphinx-build -M html docs/source docs/build/release
+
+      - name: Build Development Docs
+        run: |
+          pip install -e .
+          docs/gen_conf.py devel ${{ env.DEVEL }} Containers containers > docs/source/conf.py
+          sphinx-build -M html docs/source docs/build/development
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/build
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v5
+        id: deployment

{pythonic_fp_containers-4.0.1 → pythonic_fp_containers-4.1.0}/.gitignore

@@ -1,6 +1,8 @@
 # Minimal version - only add to when necessary
 **/__pycache__/
 dist/
+docs/build/
+docs/source/conf.py
 **/.dmypy.json
 **/.mypy_cache/
 **/.pytest_cache/

{pythonic_fp_containers-4.0.1 → pythonic_fp_containers-4.1.0}/CHANGELOG.rst

@@ -17,6 +17,24 @@ See `Semantic Versioning 2.0.0 <https://semver.org>`_.
 Releases and Important Milestones
 ---------------------------------
 
+PyPI 4.1.0 - 2026-05-14
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Documentation now in maintenance mode.
+
+Intend to make these containers final instead of inheritable.
+
+Development Status Reappraisal - 2026-05-05
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Maintainer appraised the Development Status for
+pythonic-fp-containers to be ``"3 - Alpha"``.
+
+PyPI 4.0.1 - 2026-01-19
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Docstring improvements.
+
 PyPI 4.0.0 - 2025-09-09
 ~~~~~~~~~~~~~~~~~~~~~~~
 

{pythonic_fp_containers-4.0.1 → pythonic_fp_containers-4.1.0}/PKG-INFO

@@ -1,26 +1,26 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-containers
-Version: 4.0.1
-Summary: Container with FP interfaces
+Version: 4.1.0
+Summary: Containers with FP interfaces
 Keywords: functional_containers,functional_tuple,immutable_list
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
-Requires-Python: >=3.12
+Requires-Python: >=3.13
 Description-Content-Type: text/x-rst
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pythonic-fp-circulararray>=6.0.1
+Requires-Dist: pythonic-fp-circulararray>=6.0.4
 Requires-Dist: pythonic-fp-fptools>=5.2.0
 Requires-Dist: pythonic-fp-iterables>=5.1.3
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
 Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-containers/blob/main/CHANGELOG.rst
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/containers/development/build/html/
-Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/build/html/
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/projects/containers.html
+Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-containers
 Provides-Extra: test
 
@@ -28,8 +28,8 @@ Pythonic FP - Containers
 ========================
 
 PyPI project
-`pythonic-fp.containers
-<https://pypi.org/project/pythonic-fp.containers>`_.
+`pythonic-fp-containers
+<https://pypi.org/project/pythonic-fp-containers>`_.
 
 Python package of container like data structures with functional
 programming inspired tweaks.
@@ -44,19 +44,19 @@ programming inspired tweaks.
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp>`_
+<https://grscheller.github.io/pythonic-fp/>`_
 PyPI projects.
 
 Documentation
 -------------
 
-Documentation for this project is hosted on
+Documentation and other links for this project are hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/containers>`_.
+<https://grscheller.github.io/pythonic-fp/projects/containers.html>`_.
 
 Copyright and License
 ---------------------
 
-Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
+Copyright (c) 2023-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.
 

{pythonic_fp_containers-4.0.1 → pythonic_fp_containers-4.1.0}/README.rst

@@ -2,8 +2,8 @@ Pythonic FP - Containers
 ========================
 
 PyPI project
-`pythonic-fp.containers
-<https://pypi.org/project/pythonic-fp.containers>`_.
+`pythonic-fp-containers
+<https://pypi.org/project/pythonic-fp-containers>`_.
 
 Python package of container like data structures with functional
 programming inspired tweaks.
@@ -18,18 +18,18 @@ programming inspired tweaks.
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp>`_
+<https://grscheller.github.io/pythonic-fp/>`_
 PyPI projects.
 
 Documentation
 -------------
 
-Documentation for this project is hosted on
+Documentation and other links for this project are hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/containers>`_.
+<https://grscheller.github.io/pythonic-fp/projects/containers.html>`_.
 
 Copyright and License
 ---------------------
 
-Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
+Copyright (c) 2023-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.

pythonic_fp_containers-4.1.0/docs/Makefile

@@ -0,0 +1,78 @@
+# Makefile for Sphinx documentation
+
+# Last and future releases
+#  - former needs to agree with PyPI
+#  - later needs to agree with pyproject.toml
+PROJECT_NAME = Containers
+PYPI_NAME = containers
+RELEASE_VERSION = 4.1.0
+DEVEL_VERSION = 5.0.0
+CUSTOM_VERSION = 0.0.0
+
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = build
+
+STATICDIR = source/_static
+TEMPLATEDIR = source/_templates
+
+# Put help first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean_source:
+	@rm -f "$(SOURCEDIR)"/conf.py
+
+clean_devel:
+	@rm -rf "$(BUILDDIR)"/development
+
+clean_release:
+	@rm -rf "$(BUILDDIR)"/release
+
+clean_custom:
+	@rm -rf "$(BUILDDIR)"/custom
+
+clean: clean_devel clean_release clean_custom clean_source
+	@rm -rf $(BUILDDIR)
+	@echo Removed all doc build artifacts.
+
+setup_devel: clean_devel
+	@./gen_conf.py devel "$(DEVEL_VERSION)" "$(PROJECT_NAME)" "$(PYPI_NAME)" > "$(SOURCEDIR)"/conf.py
+
+setup_release: clean_release
+	@./gen_conf.py release "$(RELEASE_VERSION)" "$(PROJECT_NAME)" "$(PYPI_NAME)" > "$(SOURCEDIR)"/conf.py
+
+setup_custom: clean_custom
+	@./gen_conf.py custom "$(CUSTOM_VERSION)" "$(PROJECT_NAME)" "$(PYPI_NAME)" > "$(SOURCEDIR)"/conf.py
+
+setup_redo: clean_custom
+	@echo Redoing custom build with a possibly reeditted conf.py
+	@./gen_conf.py redo "" "" ""
+
+# Build development labeled html docs.
+devel: Makefile setup_devel
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"/development $(SPHINXOPTS)
+
+# Build release labeled html docs.
+release: Makefile setup_release
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"/release $(SPHINXOPTS)
+
+# Build custom labeled html docs.
+custom: Makefile setup_custom
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"/custom $(SPHINXOPTS)
+
+# Build HTML docs with previous generated (possibly hand edited) source/conf.py,
+# put results in $(BUILDDIR)/custom.
+redo: Makefile setup_redo
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"/custom $(SPHINXOPTS)
+
+# Catch-all target: route all unknown targets to Sphinx and save to $(BUILDDIR)/custom.
+# Reuse a previously generated source/conf.py.
+%: Makefile setup_redo
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)"/custom $(SPHINXOPTS)
+
+.PHONY: help Makefile
+.PHONY: setup_devel setup_release setup_custom
+.PHONY: devel release
+.PHONY: clean_source clean_devel clean_release clean_custom clean

pythonic_fp_containers-4.1.0/docs/gen_conf.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python
+# Generate conf.py Sphinx configuration executable
+
+import sys
+import os
+
+project_prefix = 'Pythonic FP'
+pypi_prefix = 'pythonic-fp'
+author = 'Geoffrey R. Scheller'
+copyright = f'2023-2026, {author}'
+
+args = sys.argv[1:]
+num_args = len(args)
+
+if num_args == 4:
+    build_type, version, project_name, pypi_name = args
+    project = project_prefix + ' - ' + project_name
+    pypi_project_repo = pypi_prefix + '-' + pypi_name
+    project_url_rst = f'`{project} <https://pypi.org/project/{pypi_project_repo}/>`_'
+    homepage_url_rst = f'`{project_prefix} <https://grscheller.github.io/{pypi_prefix}/>`_'
+
+else:
+    sys.exit('Error: gen_conf.py takes exactly 4 arguments')
+
+match build_type:
+    case 'custom':
+        release = f'{version}'
+        release_string = f'**Custom PyPI Non-release version {release}**'
+    case 'devel':
+        release = f'{version}'
+        release_string = f'**Proposed PyPI release version {release}**'
+    case 'release':
+        release = f'{version}'
+        release_string = f'**PyPI release version {release}**'
+    case 'redo':
+        if not os.path.isfile('source/conf.py'):
+            sys.exit('Error: cannot redo without source/conf.py')
+        sys.exit()
+    case _:
+        sys.exit(f'Error: unknown built_type {build_type} given')
+
+print(f'''# Generated conf.py Sphinx configuration executable
+
+from typing import Any
+from sphinx.application import Sphinx
+
+project = '{project}'
+author = '{author}'
+copyright = '{copyright}'
+release = '{release}'
+release_string = '{release_string}'
+
+def skip_abc_methods(
+    app: Any, what: str, name: str, obj: Any, skip: bool, options: Any
+) -> bool:
+    if name in [
+        '__init_subclass__',
+        '__subclasshook__',
+        '__class_getitem__',
+        '__weakref__',
+    ]:
+        return True  # Skip these members
+    return skip
+
+
+def setup(app: Sphinx) -> None:
+    app.connect('autodoc-skip-member', skip_abc_methods)
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.graphviz',
+]
+
+autodoc_default_options = {{
+    'members': True,
+    'private-members': True,
+    'special-members': True,
+    'inherited-members': False,
+    'show-inheritance': True,
+}}
+autodoc_member_order = 'bysource'
+autoclass_content = 'class'
+autodoc_class_signature = 'separated'
+autodoc_typehints_format = 'short'
+autodoc_use_type_comments = True
+autodoc_docstring_signature = False
+autodoc_preserve_defaults = True
+autodoc_warningiserror = False
+
+templates_path = ['_templates']
+exclude_patterns: list[str] = []
+
+html_theme_options = {{
+    'light_css_variables': {{
+        'color-link--visited': 'var(--color-link)',
+    }},
+    'dark_css_variables': {{
+        'color-link--visited': 'var(--color-link)',
+    }},
+}}
+html_theme = 'furo'
+html_static_path = ['_static']
+html_css_files = ['custom.css']
+
+rst_epilog = """
+.. |RELEASE_STRING| replace:: {release_string}
+
+"""
+''')

pythonic_fp_containers-4.1.0/docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx>=9.1
+furo

pythonic_fp_containers-4.1.0/docs/source/_static/custom.css

@@ -0,0 +1,3 @@
+dl.field-list > dt {
+    text-transform: none !important;
+}

pythonic_fp_containers-4.1.0/docs/source/api/functional_tuple.rst

@@ -0,0 +1,6 @@
+module functional_tuple
+=======================
+
+.. automodule:: pythonic_fp.containers.functional_tuple
+    :members:
+    :special-members:

pythonic_fp_containers-4.1.0/docs/source/api/immutable_list.rst

@@ -0,0 +1,6 @@
+module immutable_list
+=====================
+
+.. automodule:: pythonic_fp.containers.immutable_list
+    :members:
+    :special-members:

pythonic_fp_containers-4.1.0/docs/source/api/index.rst

@@ -0,0 +1,19 @@
+Containers
+==========
+
+.. automodule:: pythonic_fp.containers
+    :no-members:
+    :ignore-module-all:
+    :no-index:
+
+.. toctree::
+    :caption: Functional Tuple
+    :maxdepth: 1
+
+    functional_tuple
+
+.. toctree::
+    :caption: Immutable List
+    :maxdepth: 1
+
+    immutable_list

pythonic_fp_containers-4.1.0/docs/source/changelog.rst

@@ -0,0 +1,7 @@
+Changelog
+=========
+
+Change log for the
+`pythonic-fp-containers
+<https://github.com/grscheller/pythonic-fp-containers/blob/main/CHANGELOG.rst>`_
+PyPI project.

pythonic_fp_containers-4.1.0/docs/source/description.rst

@@ -0,0 +1,7 @@
+Description
+-----------
+
+.. automodule:: pythonic_fp.containers
+    :synopsis:
+    :noindex:
+

pythonic_fp_containers-4.1.0/docs/source/index.rst

@@ -0,0 +1,30 @@
+pythonic-fp-containers
+======================
+
+Project
+`Pythonic FP - Containers <https://pypi.org/project/pythonic-fp-containers/>`_
+one of the
+`Pythonic FP <https://grscheller.github.io/pythonic-fp/>`_
+PyPI projects.
+
+|RELEASE_STRING|
+
+.. toctree::
+    :caption: Overview
+    :hidden:
+
+    self
+
+.. toctree::
+    :caption: User Documentation
+
+    description
+    usage
+    releases
+    changelog
+
+.. toctree::
+    :caption: API Documentation
+    :maxdepth: 1
+
+    api/index

pythonic_fp_containers-4.1.0/docs/source/releases.rst

@@ -0,0 +1,22 @@
+PyPI releases
+=============
+
+**pythonic-fp-containers:** pythonic_fp.containers
+
++----------------------------------------------------------------------------------------+--------------+
+| PyPI Release                                                                           | Release date |
++========================================================================================+==============+
+| `development <https://grscheller.github.io/pythonic-fp-containers/development/html/>`_ |              |
++----------------------------------------------------------------------------------------+--------------+
+| `v4.1.0 <https://grscheller.github.io/pythonic-fp-containers/release/html/>`_          | 2026-05-14   |
++----------------------------------------------------------------------------------------+--------------+
+| v4.0.1                                                                                 | 2026-01-18   |
++----------------------------------------------------------------------------------------+--------------+
+| v4.0.0                                                                                 | 2025-09-28   |
++----------------------------------------------------------------------------------------+--------------+
+| v3.0.1                                                                                 | 2025-09-09   |
++----------------------------------------------------------------------------------------+--------------+
+| v3.0.0                                                                                 | 2025-08-02   |
++----------------------------------------------------------------------------------------+--------------+
+| v2.0.0                                                                                 | 2025-07-06   |
++----------------------------------------------------------------------------------------+--------------+

pythonic_fp_containers-4.1.0/docs/source/usage.rst

@@ -0,0 +1,21 @@
+Usage
+=====
+
+How to install the package
+--------------------------
+
+Install the project into your Python environment:
+
+.. code:: console
+
+    $ pip install pythonic-fp.containers
+
+Importing the package
+---------------------
+
+Import the functional container classes into your code.
+
+.. code:: python
+
+    from pythonic_fp.containers.functional_tuple import FTuple
+    from pythonic_fp.containers.immutable_list import IList

{pythonic_fp_containers-4.0.1 → pythonic_fp_containers-4.1.0}/pyproject.toml

@@ -1,10 +1,15 @@
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
 [project]
 name = "pythonic-fp-containers"
-version = "4.0.1"
+version = "4.1.0"
 readme = "README.rst"
-requires-python = ">=3.12"
-license = { file = "LICENSE" }
-authors = [{ name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" }]
+requires-python = ">=3.13"
+authors = [
+  { name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" },
+]
 keywords = [
   "functional_containers",
   "functional_tuple",
@@ -16,11 +21,11 @@ classifiers = [
   "Intended Audience :: Developers",
   "License :: OSI Approved :: Apache Software License",
   "Operating System :: OS Independent",
-  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Typing :: Typed",
 ]
 dependencies = [
-  "pythonic-fp-circulararray>=6.0.1",
+  "pythonic-fp-circulararray>=6.0.4",
   "pythonic-fp-fptools>=5.2.0",
   "pythonic-fp-iterables>=5.1.3",
 ]
@@ -28,8 +33,8 @@ dynamic = ["description"]
 
 [project.urls]
 Changelog = "https://github.com/grscheller/pythonic-fp-containers/blob/main/CHANGELOG.rst"
-Documentation = "https://grscheller.github.io/pythonic-fp/containers/development/build/html/"
-Homepage = "https://grscheller.github.io/pythonic-fp/homepage/build/html/"
+Documentation = "https://grscheller.github.io/pythonic-fp/projects/containers.html"
+Homepage = "https://grscheller.github.io/pythonic-fp/"
 Source = "https://github.com/grscheller/pythonic-fp-containers"
 
 [project.optional-dependencies]
@@ -37,17 +42,11 @@ test = [
   "pytest>=8.4.1",
 ]
 
-[build-system]
-requires = ["flit_core>=3.12,<4"]
-build-backend = "flit_core.buildapi"
-
 [tool.flit.module]
 name = "pythonic_fp.containers"
 
 [tool.mypy]
-enable_incomplete_feature = "NewGenericSyntax"
 explicit_package_bases = true
-implicit_reexport = false
 local_partial_types = true
 namespace_packages = true
 warn_redundant_casts = true
@@ -61,19 +60,24 @@ dmypy = false
 strict = true
 report_progress = true
 
-[tool.pytest.ini_options]
-addopts = "-ra"
+[tool.pytest]
+addopts = [
+  "-ra",
+]
 consider_namespace_packages = true
 testpaths = ["tests/"]
 
 [tool.ruff]
-target-version = "py313"
+target-version = "py314"
 
 [tool.ruff.lint.flake8-quotes]
 docstring-quotes = "double"
 
 [tool.ruff.lint.per-file-ignores]
-"tests/*" = ["C901"]
+"tests/**/*.py" = [
+  "E731",
+  "C901",
+]
 "**/*.py" = ["E741"]
 
 [tool.ruff.format]

{pythonic_fp_containers-4.0.1 → pythonic_fp_containers-4.1.0}/src/pythonic_fp/containers/__init__.py

@@ -13,16 +13,15 @@
 # limitations under the License.
 
 """
-Container with FP interfaces
-----------------------------
+Containers with FP interfaces
+-----------------------------
 
-+---------------------------------------------+-----------+------------------+
-| module                                      | class     | description      |
-+=============================================+===========+==================+
-| ``pythonic_fp.containers.functional_tuple`` | FTuple    | Functional Tuple |
-+---------------------------------------------+-----------+------------------+
-| ``pythonic_fp.containers.immutable_list``   | IList     | Immutable List   |
-+---------------------------------------------+-----------+------------------+
+.. admonition:: Functional variants of Python builtins
+
+    Not sure the direction this should take.
+
+    - class **FTuple:** A tuple-like object with a functional interface.
+    - class **IList:** An immutable, hashable list-like object.
 
 """
 

{pythonic_fp_containers-4.0.1 → pythonic_fp_containers-4.1.0}/src/pythonic_fp/containers/functional_tuple.py

@@ -13,8 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Pythonic FP - Functional Tuple"""
-
 from collections.abc import Callable, Iterator
 from typing import cast, Never, overload, SupportsIndex
 from pythonic_fp.iterables.folding import accumulate
@@ -25,26 +23,42 @@ __all__ = ['FTuple']
 
 class FTuple[D](tuple[D, ...]):
     """
-    .. admonition:: Functional Tuple suitable for inheritance.
+    .. admonition:: Functional Tuple
 
+        - intended for further inheritance
         - supports both indexing and slicing
         - int multiplication and FTuple addition supported
         - addition concatenates results, resulting in a Union type
         - both left and right int multiplication supported
         - homogeneous in its data type
-        - supports being further inherited from
         - unslotted
 
+        .. note::
+
+            Example of code very early in project. Different ways
+            to use __dunders__ than what I do lately.
+
     """
 
     def __reversed__(self) -> Iterator[D]:
+        """
+        .. admonition:: reverse iter
+
+            :yields: the tuples elements in reverse order
+
+        """
         for ii in range(len(self) - 1, -1, -1):
             yield (self[ii])
 
-    def __repr__(self) -> str:
-        return f'{self.__class__.__name__}(' + ', '.join(map(repr, self)) + ')'
-
     def __eq__(self, other: object, /) -> bool:
+        """
+        .. admonition:: equality comparison
+
+            :param other: The ``object`` to which to be compared.
+            :returns: ``True`` if ``other`` is the same type and 
+                      corresponding elements compare as equal.
+
+        """
         if not isinstance(other, self.__class__):
             return False
         if (length := len(self)) != len(other):
@@ -67,6 +81,9 @@ class FTuple[D](tuple[D, ...]):
         else:
             return super().__getitem__(idx)
 
+    def __repr__(self) -> str:
+        return f'{self.__class__.__name__}(' + ', '.join(map(repr, self)) + ')'
+
     def foldl[L](
         self,
         f: Callable[[L, D], L],
@@ -74,16 +91,20 @@ class FTuple[D](tuple[D, ...]):
         start: L | None = None,
         default: L | None = None,
     ) -> L:
-        """Fold Left with optional starting and default values.
+        """
+        .. admonition:: fold left
 
-        - fold left with an optional starting value
-        - first argument of function ``f`` is for the accumulated value
+            Reduce left with optional starting and default values.
 
-        :param f: The folding function, first argument is for the accumulated value.
-        :param start: An optional starting value.
-        :param default: An optional default value if fold does not exist.
-        :raises ValueError: When ``FTuple`` empty and a start value not given.
-        :returns: The folded value if it exists, otherwise the default value.
+            :param f: The folding function, first argument is for
+                      the accumulated value.
+            :param start: An optional starting value.
+            :param default: An optional default value
+                            if fold does not exist.
+            :raises ValueError: When ``FTuple`` empty and a start value
+                                was not not given.
+            :returns: Folded value if it exists, otherwise
+                      the default value if given.
 
         """
         it_self = iter(self)
@@ -107,13 +128,20 @@ class FTuple[D](tuple[D, ...]):
         start: R | None = None,
         default: R | None = None,
     ) -> R:
-        """Fold Right with optional starting and default values.
+        """
+        .. admonition:: fold right
 
-        :param f: The folding function, second argument is for the accumulated value.
-        :param start: An optional starting value.
-        :param default: An optional default value if fold does not exist.
-        :raises ValueError: when FTuple empty and a start value not given
-        :returns: The folded value if it exists, otherwise the default value.
+            Reduce right with optional starting and default values.
+
+            :param f: The folding function, second argument is for
+                    the accumulated value.
+            :param start: An optional starting value.
+            :param default: An optional default value
+                            if fold does not exist.
+            :raises ValueError: when ``FTuple`` empty and a start value
+                                was not given
+            :returns: The folded value if it exists, otherwise
+                      the default value if given.
 
         """
         it_self = reversed(self)
@@ -131,9 +159,13 @@ class FTuple[D](tuple[D, ...]):
         return acc
 
     def copy(self) -> 'FTuple[D]':
-        """Return a shallow copy of ``FTuple`` in O(1) time & space complexity.
+        """
+        .. admonition:: copy
 
-        :returns: New ``FTuple``.
+            Return a shallow copy of ``FTuple`` in O(1)
+            time & space complexity.
+
+            :returns: A new ``FTuple`` instance.
 
         """
         return self.__class__(self)
@@ -153,14 +185,12 @@ class FTuple[D](tuple[D, ...]):
     def accummulate[L](
         self, f: Callable[[L, D], L], s: L | None = None, /
     ) -> 'FTuple[L]':
-        """Accumulate partial folds.
-
-        Accumulate partial fold with an optional starting value,
-        results in an ``FTuple``.
+        """
+        .. admonition:: accumulate partial folds
 
-        :param f: Folding function used to produce partial folds.
-        :param s: Optional starting value.
-        :returns: New ``FTuple`` of the partial folds.
+            :param f: Folding function used to produce partial folds.
+            :param s: Optional starting value.
+            :returns: New ``FTuple`` of the partial folds.
 
         """
         if s is None:
@@ -168,6 +198,13 @@ class FTuple[D](tuple[D, ...]):
         return FTuple(accumulate(self, f, s))
 
     def map[U](self, f: Callable[[D], U], /) -> 'FTuple[U]':
+        """
+        .. admonition:: map
+
+            :param f: Folding function used to produce partial folds.
+            :returns: A new ``FTuple`` instance.
+
+        """
         return FTuple(map(f, self))
 
     def bind[U](
@@ -176,13 +213,17 @@ class FTuple[D](tuple[D, ...]):
         merge_type: MergeEnum = MergeEnum.Concat,
         yield_partials: bool = False,
     ) -> 'FTuple[U] | Never':
-        """Bind function ``f`` to the ``FTuple``.
+        """
+        .. admonition:: bind
+
+            Flat map function ``f`` with the ``FTuple`` with different
+            merging strategies.
 
-        :param f: Function ``D -> FTuple[U]``
-        :param merge_type: ``MergeEnum`` to determine how to merge the result. 
-        :param yield_partials: Yield unmatched values if ``MergeEnum`` given as merge type.
-        :return: Resulting ``FTuple``.
-        :raises ValueError: If given an unknown merge enumeration.
+            :param f: Function ``D -> FTuple[U]``
+            :param merge_type: ``MergeEnum`` to determine how to merge the result.
+            :param yield_partials: Yield unmatched values if ``MergeEnum`` given as merge type.
+            :returns: A new ``FTuple`` instance.
+            :raises ValueError: If given an unknown merge enumeration.
 
         """
         return FTuple(

{pythonic_fp_containers-4.0.1 → pythonic_fp_containers-4.1.0}/src/pythonic_fp/containers/immutable_list.py

@@ -12,8 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Pythonic FP - Immutable guaranteed hashable lists."""
-
 from collections.abc import Callable, Iterable, Iterator, Hashable
 from typing import cast, Never, overload
 from pythonic_fp.iterables.folding import accumulate
@@ -24,7 +22,7 @@ __all__ = ['IList']
 
 class IList[D](Hashable):
     """
-    .. admonition:: Immutable List like data structure.
+    .. admonition:: immutable list like data structure
 
         - hashability should be enforced by LSP tooling
         - hashability will be enforced at runtime
@@ -39,16 +37,18 @@ class IList[D](Hashable):
     __slots__ = ('_ds', '_len', '_hash')
     __match_args__ = ('_ds', '_len')
 
-    def __init__(self, *dss: Iterable[D]) -> None:
+    def __init__(self, *ds: Iterable[D]) -> None:
         """
-        :param dss: 0 or 1 iterables
+        .. admonition:: init
+
+            :param ds: One optional iterable.
 
         """
-        if (size := len(dss)) > 1:
+        if (size := len(ds)) > 1:
             msg = f'IList expects at most 1 iterable argument, got {size}'
             raise ValueError(msg)
         else:
-            self._ds: tuple[D, ...] = tuple(dss[0]) if size == 1 else tuple()
+            self._ds: tuple[D, ...] = tuple(ds[0]) if size == 1 else tuple()
             self._len = len(self._ds)
             try:
                 self._hash = hash((self._len, 42) + self._ds)
@@ -57,26 +57,55 @@ class IList[D](Hashable):
                 raise TypeError(msg)
 
     def __hash__(self) -> int:
+        """
+        .. admonition:: hash
+
+            Hashability enforced at runtime by initializer.
+
+            :returns: Hash value.
+
+        """
         return self._hash
 
     def __iter__(self) -> Iterator[D]:
+        """
+        .. admonition:: iterate
+
+            Forward iterate, left to right.
+
+            :yields: The contained values.
+
+        """
         return iter(self._ds)
 
     def __reversed__(self) -> Iterator[D]:
+        """
+        .. admonition:: iterate
+
+            Reverse iterate, left to right.
+
+            :yields: The contained values in reverse order.
+
+        """
         return reversed(self._ds)
 
     def __bool__(self) -> bool:
+        """
+        .. admonition:: bool
+
+            :returns: ``True`` if not empty, ``False`` if empty.
+
+        """
         return bool(self._ds)
 
     def __len__(self) -> int:
-        return len(self._ds)
-
-    def __repr__(self) -> str:
-        return 'immutable_list(' + ', '.join(map(repr, self)) + ')'
+        """
+        .. admonition:: len
 
-    def __str__(self) -> str:
-        return '((' + ', '.join(map(repr, self)) + '))'
+            :returns: The number of items in the ``Ilist``.
 
+        """
+        return len(self._ds)
     def __eq__(self, other: object, /) -> bool:
         if not isinstance(other, IList):
             return NotImplemented  # magic object
@@ -92,10 +121,37 @@ class IList[D](Hashable):
     def __getitem__(self, idx: slice, /) -> 'IList[D]': ...
 
     def __getitem__(self, idx: slice | int, /) -> 'IList[D] | D':
+        """
+        .. admonition:: getitem
+
+            Indexable and sliceable but otherwise immutable.
+
+            :param idx: Either a ``slice`` or and ``index``.
+            :returns: A slice or the value.
+
+        """
         if isinstance(idx, slice):
             return IList(self._ds[idx])
         return self._ds[idx]
 
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            :returns: A string to reproduce the value.
+
+        """
+        return 'immutable_list(' + ', '.join(map(repr, self)) + ')'
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            :returns: A string meaningful to an end user.
+
+        """
+        return '((' + ', '.join(map(repr, self)) + '))'
+
     def foldl[L](
         self,
         f: Callable[[L, D], L],
@@ -103,13 +159,16 @@ class IList[D](Hashable):
         start: L | None = None,
         default: L | None = None,
     ) -> L | None:
-        """Fold Left.
+        """
+        .. admonition:: fold left
 
-        :param f: Folding function, first argument is for the accumulated value.
-        :param start: Optional starting value.
-        :param default: Optional default value if fold does not exist.
-        :returns: Folded value.
-        :raises ValueError: When empty and a start value not given.
+            :param f: Folding function, first argument is for
+                      the accumulated value.
+            :param start: Optional starting value.
+            :param default: Optional default value if fold does not exist.
+            :returns: Left folded value.
+            :raises ValueError: When empty and neither a start value or
+                                default value not given.
 
         """
         it = iter(self._ds)
@@ -135,13 +194,16 @@ class IList[D](Hashable):
         start: R | None = None,
         default: R | None = None,
     ) -> R | None:
-        """Fold Right.
+        """
+        .. admonition:: fold right
 
-        :param f: Folding function, second argument is for the accumulated value.
-        :param start: Optional starting value.
-        :param default: Optional default value if fold does not exist.
-        :returns: Folded value.
-        :raises ValueError: When empty and a start value not given.
+            :param f: Folding function, second argument is for
+                    the accumulated value.
+            :param start: Optional starting value.
+            :param default: Optional default value if fold does not exist.
+            :returns: Right folded value.
+            :raises ValueError: When empty and neither a start value or
+                                default value not given.
 
         """
         it = reversed(self._ds)
@@ -161,6 +223,18 @@ class IList[D](Hashable):
         return acc
 
     def __add__(self, other: 'IList[D]', /) -> 'IList[D]':
+        """
+        .. admonition:: add by concatenation
+
+            :param other: The ``other`` same typed ``IList``.
+            :returns: New ``IList`` instance with concatenated values.
+            :raises ValueError: When ``other`` is not an ``IList``.
+
+            .. admonition:: TODO
+
+                Return ``NotImplemented`` if appropriate?
+
+        """
         if not isinstance(other, IList):
             msg = 'IList being added to something not an IList'
             raise ValueError(msg)
@@ -168,22 +242,45 @@ class IList[D](Hashable):
         return IList(concat(self, other))
 
     def __mul__(self, num: int, /) -> 'IList[D]':
+        """
+        .. admonition:: add by concatenation
+
+            :param other: The ``other`` same typed ``IList``.
+            :returns: New ``IList`` instance with concatenated values.
+            :raises ValueError: When ``other`` is not an ``IList``.
+
+            .. admonition:: TODO
+
+                Consider returning ``NotImplemented`` if appropriate?
+                Maybe define a "column vector" version?
+
+        """
         return IList(self._ds.__mul__(num if num > 0 else 0))
 
     def __rmul__(self, num: int, /) -> 'IList[D]':
+        """
+        .. admonition:: concatenation with itself
+
+            :param num: Number of times to concatenate ``IList``
+                        with itself.
+            :returns: A new ``IList`` instance with concatenated values.
+            :raises ValueError: When ``other`` is not an ``IList``.
+
+        """
         return IList(self._ds.__mul__(num if num > 0 else 0))
 
     def accummulate[L](
         self, f: Callable[[L, D], L], s: L | None = None, /
     ) -> 'IList[L]':
-        """Accumulate partial folds.
+        """
+        .. admonition:: accumulate partial folds
 
-        Accumulate partial fold with an optional starting value,
-        results in an ``IList``.
+            Accumulate partial fold with an optional starting value,
+            results in an ``IList``.
 
-        :param f: Folding function used to produce partial folds.
-        :param s: Optional starting value.
-        :returns: New ``FTuple`` of the partial folds.
+            :param f: Folding function used to produce partial folds.
+            :param s: Optional starting value.
+            :returns: New ``IList`` of the partial folds.
 
         """
         if s is None:
@@ -191,6 +288,13 @@ class IList[D](Hashable):
         return IList(accumulate(self, f, s))
 
     def map[U](self, f: Callable[[D], U], /) -> 'IList[U]':
+        """
+        .. admonition:: map
+
+            :parameter f: Function to map over the ``IList``.
+            :returns: A new ``IList`` instance with the mapped values.
+
+        """
         return IList(map(f, self))
 
     def bind[U](
@@ -199,13 +303,17 @@ class IList[D](Hashable):
         merge_enum: MergeEnum = MergeEnum.Concat,
         yield_partials: bool = False,
     ) -> 'IList[U] | Never':
-        """Bind function ``f`` to the ``IList``.
-
-        :param f: Function ``D -> IList[U]``
-        :param merge_type: ``MergeEnum`` to determine how to merge the result. 
-        :param yield_partials: Yield unmatched values if ``MergeEnum`` given as merge type.
-        :return: Resulting ``IList``.
-        :raises ValueError: If given an unknown merge enumeration.
+        """
+        .. admonition:: bind
+
+            :param f: Function ``D -> IList[U]`` to bind with different
+                      merge strategies.
+            :param merge_type: ``MergeEnum`` to determine how to merge
+                               the result.
+            :param yield_partials: Yield unmatched values if ``MergeEnum``
+                                   given as merge type.
+            :return: New ``IList`` instance.
+            :raises ValueError: If given an unknown merge enumeration.
 
         """
         return IList(

{pythonic_fp_containers-4.0.1 → pythonic_fp_containers-4.1.0}/src/pythonic_fp/containers/immutable_list.pyi

@@ -7,7 +7,7 @@ __all__ = ['IList']
 
 class IList[D](Hashable):
     __match_args__: Incomplete
-    def __init__(self, *dss: Iterable[D]) -> None: ...
+    def __init__(self, *ds: Iterable[D]) -> None: ...
     def __hash__(self) -> int: ...
     def __iter__(self) -> Iterator[D]: ...
     def __reversed__(self) -> Iterator[D]: ...