pluggable-namespace 1.0.0__tar.gz

pluggable_namespace-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+graft src
+global-exclude __pycache__ *.py[cod]
+global-exclude *.egg-info

pluggable_namespace-1.0.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.2
+Name: pluggable-namespace
+Version: 1.0.0
+Summary: Pluggable namespaces
+Author-email: Tyler Levy Conde <yonstib@gmail.com>
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.11
+Description-Content-Type: text/x-rst
+Requires-Dist: aioconsole
+Requires-Dist: aiofiles
+Requires-Dist: aiologger
+Requires-Dist: argparse
+Requires-Dist: PyYaml
+Provides-Extra: console
+Requires-Dist: aiomonitor; extra == "console"
+Requires-Dist: prompt-toolkit; extra == "console"
+Provides-Extra: rend
+Requires-Dist: aio-yte; extra == "rend"
+Requires-Dist: jinja2; extra == "rend"
+Requires-Dist: toml; extra == "rend"
+Provides-Extra: seed
+Requires-Dist: copier; extra == "seed"
+Provides-Extra: test
+Requires-Dist: pexpect; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: setuptools; extra == "test"
+Provides-Extra: full
+Requires-Dist: aiomonitor; extra == "full"
+Requires-Dist: prompt-toolkit; extra == "full"
+Requires-Dist: aio-yte; extra == "full"
+Requires-Dist: jinja2; extra == "full"
+Requires-Dist: toml; extra == "full"
+Requires-Dist: copier; extra == "full"
+Requires-Dist: pexpect; extra == "full"
+Requires-Dist: pytest; extra == "full"
+Requires-Dist: pytest-asyncio; extra == "full"
+Requires-Dist: setuptools; extra == "full"
+Dynamic: provides-extra
+
+===================
+Pluggable Namespace
+===================
+This project is designed to facilitate the creation and management of pluggable software architectures using namespaces. The concept of pluggable namespaces enables the development of software that is modular and easy to extend.
+
+Pluggable namespaces provide a framework for constructing applications composed entirely of interchangeable modules. This approach allows developers to scale their projects smoothly and integrate complex software components seamlessly.
+
+Using pluggable namespaces, developers can build software in smaller, maintainable components. These components can then be combined and deployed as a single entity, simplifying the deployment process.
+
+All of this is achieved using Python, one of the world's most popular and powerful programming languages.
+
+Installation
+============
+
+You can install ``pluggable-namespace`` from PyPI:
+
+.. code-block:: bash
+
+    pip3 install pluggable-namespace
+
+Creating a pluggable application can be accomplished with just a few lines of code. The heart of every pluggable-namespace project is the creation of a hub, adding dynamic subsystems, and interacting with them through the hub's namespace.
+
+.. code-block:: python
+
+    import pns.shim
+    import asyncio
+
+
+    async def main():
+        hub = await pns.shim.loaded_hub()
+        await hub.my_sub.init.cli()
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+
+Configuration
+=============
+When building a pluggable-namespace app, all configuration settings are stored in a ``config.yaml`` file.
+
+.. code-block:: yaml
+
+    # Each configuration option for your module
+    config:
+      my_namespace:
+        my_opt:
+          default: True
+
+    # Options exposed on the CLI when your app controls the CLI
+    cli_config:
+      my_namespace:
+        my_opt:
+          help: Description of this option
+          subcommands:
+            - my_subcommand
+          group: My arg group
+
+    # Subcommands to expose for your project
+    subcommands:
+      my_namespace:
+        my_subcommand:
+          help: My subcommand
+
+    # Dynamic namespaces that your app merges onto and which folders extend those namespaces
+    dyne:
+      my_dyne:
+        - src_dir
+
+    # Python imports that your app uses, to be added to hub.lib for your app
+    import:
+      - asyncio
+      - importlib
+      - importlib.resources
+      - os
+      - toml
+
+
+From the example above, all arguments are loaded onto the namespace under hub.OPT.my_namespace.
+One ``config.yaml`` can add configuration options to multiple namespaces.
+They are merged in the order found in sys.path.
+
+Extending Namespaces
+====================
+
+locally
+-------
+
+Extending ``pluggable-namespace`` is straightforward with dynamic namespaces.
+Extend any dynamic namespace on the hub by adding a directory containing a "config.yaml" to PYTHONPATH.
+
+.. code-block:: bash
+
+    export PYTHONPATH=$PYTHONPATH:/path/to/project_root
+
+Add a config.yaml to that directory:
+
+.. code-block:: yaml
+
+    # project_root/config.yaml
+    dyne:
+      namespace:
+        # This references the directory project_root/foo
+        - foo
+
+Now, every Python file in ``project_root/foo`` will be added to the hub under ``hub.namespace``.
+
+
+With PyPI
+---------
+
+You can use the ``seed`` command to create all the boiler-plate code you need for a pluggable-namespace project.
+
+.. code-block:: bash
+
+    hub seed.init.cli /path/to/project_root name=my_project
+
+
+Now you can add all your code to /path/to/project_root/src/my_project

pluggable_namespace-1.0.0/README.rst

@@ -0,0 +1,117 @@
+===================
+Pluggable Namespace
+===================
+This project is designed to facilitate the creation and management of pluggable software architectures using namespaces. The concept of pluggable namespaces enables the development of software that is modular and easy to extend.
+
+Pluggable namespaces provide a framework for constructing applications composed entirely of interchangeable modules. This approach allows developers to scale their projects smoothly and integrate complex software components seamlessly.
+
+Using pluggable namespaces, developers can build software in smaller, maintainable components. These components can then be combined and deployed as a single entity, simplifying the deployment process.
+
+All of this is achieved using Python, one of the world's most popular and powerful programming languages.
+
+Installation
+============
+
+You can install ``pluggable-namespace`` from PyPI:
+
+.. code-block:: bash
+
+    pip3 install pluggable-namespace
+
+Creating a pluggable application can be accomplished with just a few lines of code. The heart of every pluggable-namespace project is the creation of a hub, adding dynamic subsystems, and interacting with them through the hub's namespace.
+
+.. code-block:: python
+
+    import pns.shim
+    import asyncio
+
+
+    async def main():
+        hub = await pns.shim.loaded_hub()
+        await hub.my_sub.init.cli()
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+
+Configuration
+=============
+When building a pluggable-namespace app, all configuration settings are stored in a ``config.yaml`` file.
+
+.. code-block:: yaml
+
+    # Each configuration option for your module
+    config:
+      my_namespace:
+        my_opt:
+          default: True
+
+    # Options exposed on the CLI when your app controls the CLI
+    cli_config:
+      my_namespace:
+        my_opt:
+          help: Description of this option
+          subcommands:
+            - my_subcommand
+          group: My arg group
+
+    # Subcommands to expose for your project
+    subcommands:
+      my_namespace:
+        my_subcommand:
+          help: My subcommand
+
+    # Dynamic namespaces that your app merges onto and which folders extend those namespaces
+    dyne:
+      my_dyne:
+        - src_dir
+
+    # Python imports that your app uses, to be added to hub.lib for your app
+    import:
+      - asyncio
+      - importlib
+      - importlib.resources
+      - os
+      - toml
+
+
+From the example above, all arguments are loaded onto the namespace under hub.OPT.my_namespace.
+One ``config.yaml`` can add configuration options to multiple namespaces.
+They are merged in the order found in sys.path.
+
+Extending Namespaces
+====================
+
+locally
+-------
+
+Extending ``pluggable-namespace`` is straightforward with dynamic namespaces.
+Extend any dynamic namespace on the hub by adding a directory containing a "config.yaml" to PYTHONPATH.
+
+.. code-block:: bash
+
+    export PYTHONPATH=$PYTHONPATH:/path/to/project_root
+
+Add a config.yaml to that directory:
+
+.. code-block:: yaml
+
+    # project_root/config.yaml
+    dyne:
+      namespace:
+        # This references the directory project_root/foo
+        - foo
+
+Now, every Python file in ``project_root/foo`` will be added to the hub under ``hub.namespace``.
+
+
+With PyPI
+---------
+
+You can use the ``seed`` command to create all the boiler-plate code you need for a pluggable-namespace project.
+
+.. code-block:: bash
+
+    hub seed.init.cli /path/to/project_root name=my_project
+
+
+Now you can add all your code to /path/to/project_root/src/my_project

pluggable_namespace-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools", "wheel", "Cython"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pluggable-namespace"
+version = "1.0.0"
+description = "Pluggable namespaces"
+readme = "README.rst"
+authors = [
+    {name = "Tyler Levy Conde", email = "yonstib@gmail.com"},
+]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: Apache Software License",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "aioconsole",
+    "aiofiles",
+    "aiologger",
+    "argparse",
+    "PyYaml",
+]
+dynamic = ["optional-dependencies"]
+
+[project.scripts]
+hub = "hub.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.pytest.ini_options]
+testpaths = "test"
+addopts = "--tb native --full-trace --color=yes -vv"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.cython-lint]
+max-line-length = 120

pluggable_namespace-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pluggable_namespace-1.0.0/setup.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+from setuptools import setup
+from setuptools.extension import Extension
+from Cython.Build import cythonize
+
+extensions = [
+    Extension(name="pns._ccontract", sources=["src/pns/_contract.py"]),
+    Extension(name="pns._cdata", sources=["src/pns/_data.py"]),
+    Extension(name="pns._chub", sources=["src/pns/_hub.py"]),
+]
+
+SETUP_DIRNAME = Path(__file__).parent
+
+requirement_extras = {}
+REQUIREMENTS = SETUP_DIRNAME / "requirement"
+assert REQUIREMENTS.exists()
+for req_file in REQUIREMENTS.glob("*.txt"):
+    with open(req_file) as f:
+        requirement_extras[req_file.stem] = sorted(
+            line for line in f.read().splitlines() if line.strip()
+        )
+
+requirement_extras["full"] = sum(requirement_extras.values(), [])
+
+setup(
+    extras_require=requirement_extras,
+    ext_modules=cythonize(extensions),
+    include_package_data=True,
+)

pluggable_namespace-1.0.0/src/_config/config.yaml

@@ -0,0 +1,41 @@
+
+cli_config:
+  pns:
+    config:
+      default: ~/.pns/config.yaml
+      os: PNS_CONFIG
+      help: The config file used for PNS
+      group: Config Options
+      options:
+      - -c
+      subcommands:
+      - __global__
+
+dyne:
+  config:
+    - plugin
+
+import:
+  - aiofiles
+  - aiofiles.os
+  - aiologger.handlers.files
+  - argparse
+  - asyncio
+  - ast
+  - collections
+  - pns.contract
+  - pns.data
+  - pns.exc
+  - pns.hub
+  - importlib
+  - importlib.resources
+  - logging
+  - msgpack
+  - os
+  - pathlib
+  - pickle
+  - signal
+  - sys
+  - traceback
+  - yaml
+  - typing

pluggable_namespace-1.0.0/src/_config/plugin/choices.py

@@ -0,0 +1,37 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Handle choices that may come from a loaded mod.
+
+    You specify a sub on the hub for "choices" to dynamically use the loaded mods of that sub as the choices
+
+    I.e.
+
+    config:
+      my_app:
+        my_opt:
+          choices:
+            my_sub
+
+    Otherwise, you can specify a list of static choices that may be used
+
+    I.e.
+
+    config:
+      my_app:
+        my_opt:
+          choices:
+            - choice_1
+            - choice_2
+    """
+    choices = opts.pop("choices", ())
+    if isinstance(choices, str):
+        finder = hub
+        for part in choices.split("."):
+            try:
+                finder = getattr(finder, part)
+            except AttributeError:
+                return {}
+
+        opts["choices"] = sorted(finder)
+
+    return {}

pluggable_namespace-1.0.0/src/_config/plugin/contract/init.py

@@ -0,0 +1 @@
+async def sig_parse_opt(hub, opts: dict[str, object]) -> dict[str, object]: ...

pluggable_namespace-1.0.0/src/_config/plugin/default.py

@@ -0,0 +1,30 @@
+async def __init__(hub):
+    hub._.REF_PATTERN = hub.lib.re.compile(r"^hub\.(\w+(\.\w+)+)\(\)$")
+
+
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Remove 'default' from the argument opts, it will be handled by the config prioritizer, not argparse.
+    If the "default" is a function that exists on the hub, then call it to get the default value.
+    This allows you to call a function on the hub to do more processing on the default.
+    This could be useful for using a different value for the default based on OS.
+
+    I.e.
+
+    config:
+      my_app:
+        my_opt:
+          default: hub.my_sub.mod.func()
+    """
+    default = opts.pop("default", None)
+
+    if default and isinstance(default, str):
+        match = hub._.REF_PATTERN.match(default)
+        if match:
+            ref = match.group(1)
+            func = hub.lib.pns.ref.find(hub, ref)
+            default = func()
+            if hub.lib.asyncio.iscoroutine(default):
+                default = await default
+
+    return {"default": default}

pluggable_namespace-1.0.0/src/_config/plugin/display_priority.py

@@ -0,0 +1,34 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Handle the display priority of positional arguments.
+    This ensures that positional arguments appear in the defined order
+
+    I.e.
+
+        config:
+          my_app:
+            my_opt_1:
+              positional: True
+              display_priority: 1
+            my_opt_2:
+              positional: True
+              display_priority: 2
+    """
+    display_priority = opts.pop("display_priority", None)
+    return {"display_priority": display_priority}
+
+
+async def sort(hub, cli_args: list[dict[str, object]]) -> list[dict[str, object]]:
+    """
+    Sort the CLI arguments by display_priority.
+    The negative display_priorities were applied to args with no display priority,
+    They will come in the order they were defined
+    """
+    # Sort arguments by display_priority
+    return sorted(
+        cli_args,
+        key=lambda opt: (
+            opt["extra"]["display_priority"] is None,
+            opt["extra"]["display_priority"],
+        ),
+    )

pluggable_namespace-1.0.0/src/_config/plugin/group.py

@@ -0,0 +1,31 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    This config value groups arguments together in the --help text.
+
+    config:
+      my_app:
+        my_opt:
+          group: my_group
+        other_opt:
+          group: my_group
+    """
+    group = opts.pop("group", False)
+    return {"group": group}
+
+
+async def merge(hub, name: str, groups: dict[str, object], subcmd: str, subparser):
+    """
+    Merge the group into the subparser if a group name is provided.
+
+    Args:
+        name (str): The name of the group.
+        groups (dict): The existing groups dictionary.
+        subcmd (str): The subcommand name.
+        subparser (ArgumentParser): The subparser instance.
+
+    Returns:
+        ArgumentParser: The argument group added to the subparser.
+    """
+    if name:
+        return groups[subcmd].setdefault(name, subparser.add_argument_group(name))
+    return subparser