soft-deps 0.1.1__py3-none-any.whl

soft_deps/__init__.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+
+from ._version import __version__
+from ._version import __short_description__
+from ._version import __license__
+from ._version import __author__
+from ._version import __author_email__
+from ._version import __maintainer__
+from ._version import __maintainer_email__

soft_deps/_version.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python
+# This file is automatically generated by pywf script
+# based on the content in pyproject.toml file
+
+__version__ = "0.1.1"
+__short_description__ = "Elegant optional dependency management for Python - full IDE support when available, graceful degradation when missing."
+__license__ = "MIT"
+__author__ = "Sanhe Hu"
+__author_email__ = "husanhe@email.com"
+__maintainer__ = "Sanhe Hu"
+__maintainer_email__ = "husanhe@email.com"
+
+# run this script to print out the version number
+if __name__ == "__main__":  # pragma: no cover
+    print(__version__)

soft_deps/api.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+
+from .impl import MissingDependency

soft_deps/impl.py

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+
+"""
+soft-deps is a Python pattern for elegant optional dependency management that
+prioritizes developer experience over lazy loading. Unlike true lazy imports,
+soft-deps immediately attempts to import dependencies at module load time -
+if the dependency is installed, you get the real module with full functionality.
+If it's missing, you get a helpful proxy object that provides complete IDE
+type hints and auto-completion, but raises informative error messages only
+when you actually try to use the missing functionality. This approach gives you
+the best of both worlds: seamless development experience with full IDE support
+when dependencies are available, and graceful degradation with clear
+installation guidance when they're not, all while maintaining zero code
+invasiveness in your implementation.
+"""
+
+from functools import total_ordering
+
+
+@total_ordering
+class MissingDependency:
+    def __init__(
+        self,
+        name: str,
+        error_message: str = "please install it",
+    ):
+        self.name = name
+        self.error_message = error_message
+
+    def _raise_error(self):
+        raise ImportError(f"To use `{self.name}`, {self.error_message}.")
+
+    def __repr__(self):  # pragma: no cover
+        self._raise_error()
+
+    def __getattr__(self, attr: str):  # pragma: no cover
+        self._raise_error()
+
+    def __getitem__(self, item):  # pragma: no cover
+        self._raise_error()
+
+    def __call__(self, *args, **kwargs):  # pragma: no cover
+        self._raise_error()
+
+    def __iter__(self):  # pragma: no cover
+        self._raise_error()
+
+    def __eq__(self, other):  # pragma: no cover
+        self._raise_error()
+
+    def __lt__(self, other):  # pragma: no cover
+        self._raise_error()
+
+    def __hash__(self):  # pragma: no cover
+        self._raise_error()
+
+    def __add__(self, other):  # pragma: no cover
+        self._raise_error()
+
+    def __sub__(self, other):  # pragma: no cover
+        self._raise_error()
+
+    def __mul__(self, other):  # pragma: no cover
+        self._raise_error()
+
+    def __truediv__(self, other):  # pragma: no cover
+        self._raise_error()

soft_deps/paths.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+
+from pathlib import Path
+
+dir_here = Path(__file__).absolute().parent
+dir_package = dir_here
+PACKAGE_NAME = dir_package.name
+
+dir_project_root = dir_package.parent
+
+# ------------------------------------------------------------------------------
+# Virtual Environment Related
+# ------------------------------------------------------------------------------
+dir_venv = dir_project_root / ".venv"
+dir_venv_bin = dir_venv / "bin"
+
+# virtualenv executable paths
+bin_pytest = dir_venv_bin / "pytest"
+
+# ------------------------------------------------------------------------------
+# Test Related
+# ------------------------------------------------------------------------------
+dir_htmlcov = dir_project_root / "htmlcov"
+path_cov_index_html = dir_htmlcov / "index.html"
+dir_unit_test = dir_project_root / "tests"
+dir_int_test = dir_project_root / "tests_int"
+dir_load_test = dir_project_root / "tests_load"
+
+# ------------------------------------------------------------------------------
+# Doc Related
+# ------------------------------------------------------------------------------
+dir_docs_source = dir_project_root / "docs" / "source"
+dir_docs_build_html = dir_project_root / "docs" / "build" / "html"

soft_deps/vendor/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+

soft_deps/vendor/pytest_cov_helper.py

@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+import contextlib
+import subprocess
+from pathlib import Path
+
+__version__ = "0.2.1"
+
+
+@contextlib.contextmanager
+def temp_cwd(path: Path):
+    """
+    Temporarily set the current working directory (CWD) and automatically
+    switch back when it's done.
+    """
+    cwd = os.getcwd()
+    os.chdir(str(path))
+    try:
+        yield path
+    finally:
+        os.chdir(cwd)
+
+
+def run_unit_test(
+    script: str,
+    root_dir: str,
+):
+    """
+    Run ``pytest -s --tb=native /path/to/script.py`` Command.
+
+    :param script: the path to test script
+    :param root_dir: the dir you want to temporarily set as cwd
+    """
+    bin_pytest = Path(sys.executable).parent / "pytest"
+    args = [
+        f"{bin_pytest}",
+        "-s",
+        "--tb=native",
+        script,
+    ]
+    with temp_cwd(Path(root_dir)):
+        subprocess.run(args)
+
+
+def run_cov_test(
+    script: str,
+    module: str,
+    root_dir: str,
+    htmlcov_dir: str,
+    preview: bool = False,
+    is_folder: bool = False,
+):
+    """
+    The pytest-cov plugin gives you the coverage for entire project. What if
+    I want run per-module test independently and get per-module coverage?
+
+    This is a simple wrapper around pytest + coverage cli command. Allow you to run
+    coverage test from Python script and set the code coverage measurement scope.
+
+    Usage example:
+
+    suppose you have a source code folder structure like this::
+
+        /dir_git_repo/
+        /dir_git_repo/my_library
+        /dir_git_repo/my_library/__init__.py
+        /dir_git_repo/my_library/module1.py
+        /dir_git_repo/my_library/module2.py
+
+    In your module 1 unit test script, you can do this:
+
+    .. code-block:: python
+
+        from my_library.module1 import func1, func2
+
+        def test_func1():
+            pass
+
+        def test_func2():
+            pass
+
+        if __name__ == "__main__":
+            from fixa.pytest_cov_helper import run_cov_test
+
+            run_cov_test(
+                script=__file__,
+                module="my_library.module1", # test scope is the module1.py
+                root_dir="/path/to/dir_git_repo",
+                htmlcov_dir="/path/to/dir_git_repo/htmlcov",
+            )
+
+    In your all modules unit test script, you can do this:
+
+    .. code-block:: python
+
+        if __name__ == "__main__":
+            from fixa.pytest_cov_helper import run_cov_test
+
+            run_cov_test(
+                script=__file__,
+                module="my_library", # test scope is the my_library/
+                root_dir="/path/to/dir_git_repo",
+                htmlcov_dir="/path/to/dir_git_repo/htmlcov",
+                is_folder=True, # my_library is a folder
+            )
+
+    :param script: the test script absolute path
+    :param module: the dot notation to the python module you want to calculate
+        coverage
+    :param root_dir: the dir to dump coverage results binary file
+    :param htmlcov_dir: the dir to dump HTML output
+    :param preview: whether to open the HTML output in web browser after the test
+    :param is_folder: whether the module is a folder
+
+    Reference:
+
+    - https://pypi.org/project/pytest-cov/
+    """
+    bin_pytest = Path(sys.executable).parent / "pytest"
+    if is_folder:
+        script = f"{Path(script).parent}"
+    if module.endswith(".py"):  # pragma: no cover
+        module = module[:-3]
+    args = [
+        f"{bin_pytest}",
+        "-s",
+        "--tb=native",
+        f"--rootdir={root_dir}",
+        f"--cov={module}",
+        "--cov-report",
+        "term-missing",
+        "--cov-report",
+        f"html:{htmlcov_dir}",
+        script,
+    ]
+    with temp_cwd(Path(root_dir)):
+        subprocess.run(args)
+    if preview:  # pragma: no cover
+        platform = sys.platform
+        if platform in ["win32", "cygwin"]:
+            open_command = "start"
+        elif platform in ["darwin", "linux"]:
+            open_command = "open"
+        else:
+            raise NotImplementedError
+        subprocess.run([open_command, f"{Path(htmlcov_dir).joinpath('index.html')}"])

soft_deps-0.1.1.dist-info/AUTHORS.rst

@@ -0,0 +1,15 @@
+.. _about_author:
+
+About the Author
+------------------------------------------------------------------------------
+::
+
+   (\ (\
+   ( -.-)o
+   o_(")(")
+
+**Sanhe Hu** is a seasoned software engineer with a deep passion for Python development since 2010. As an author and maintainer of `150+ open-source Python projects <https://pypi.org/user/machugwu/>`_, with over `15 million monthly downloads <https://github.com/MacHu-GWU>`_, I bring a wealth of experience to the table. As a Senior Solution Architect and Subject Matter Expert in AI, Data, Amazon Web Services, Cloud Engineering, DevOps, I thrive on helping clients with platform design, enterprise architecture, and strategic roadmaps.
+
+Talk is cheap, show me the code:
+
+- My Github: https://github.com/MacHu-GWU

soft_deps-0.1.1.dist-info/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sanhe Hu <husanhe@email.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

soft_deps-0.1.1.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.3
+Name: soft_deps
+Version: 0.1.1
+Summary: Elegant optional dependency management for Python - full IDE support when available, graceful degradation when missing.
+License: MIT
+Author: Sanhe Hu
+Author-email: husanhe@email.com
+Maintainer: Sanhe Hu
+Maintainer-email: husanhe@email.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: auto
+Provides-Extra: dev
+Provides-Extra: doc
+Provides-Extra: test
+Requires-Dist: Sphinx (>=7.4.7,<8.0.0) ; extra == "doc"
+Requires-Dist: build (>=1.2.1,<2.0.0) ; extra == "dev"
+Requires-Dist: docfly (==3.0.0) ; extra == "doc"
+Requires-Dist: furo (==2024.8.6) ; extra == "doc"
+Requires-Dist: ipython (>=8.18.1,<8.19.0) ; extra == "doc"
+Requires-Dist: nbsphinx (>=0.8.12,<1.0.0) ; extra == "doc"
+Requires-Dist: pygments (>=2.18.0,<3.0.0) ; extra == "doc"
+Requires-Dist: pytest (>=8.2.2,<9.0.0) ; extra == "test"
+Requires-Dist: pytest-cov (>=6.0.0,<7.0.0) ; extra == "test"
+Requires-Dist: rich (>=13.8.1,<14.0.0) ; extra == "dev"
+Requires-Dist: rstobj (==1.2.1) ; extra == "doc"
+Requires-Dist: sphinx-copybutton (>=0.5.2,<1.0.0) ; extra == "doc"
+Requires-Dist: sphinx-design (>=0.6.1,<1.0.0) ; extra == "doc"
+Requires-Dist: sphinx-jinja (>=2.0.2,<3.0.0) ; extra == "doc"
+Requires-Dist: twine (>=6.0.0,<7.0.0) ; extra == "dev"
+Requires-Dist: wheel (>=0.45.0,<1.0.0) ; extra == "dev"
+Project-URL: Changelog, https://github.com/MacHu-GWU/soft_deps-project/blob/main/release-history.rst
+Project-URL: Documentation, https://soft-deps.readthedocs.io/en/latest/
+Project-URL: Download, https://pypi.org/pypi/soft-deps#files
+Project-URL: Homepage, https://github.com/MacHu-GWU/soft_deps-project
+Project-URL: Issues, https://github.com/MacHu-GWU/soft_deps-project/issues
+Project-URL: Repository, https://github.com/MacHu-GWU/soft_deps-project
+Description-Content-Type: text/x-rst
+
+
+.. image:: https://readthedocs.org/projects/soft-deps/badge/?version=latest
+    :target: https://soft-deps.readthedocs.io/en/latest/
+    :alt: Documentation Status
+
+.. image:: https://github.com/MacHu-GWU/soft_deps-project/actions/workflows/main.yml/badge.svg
+    :target: https://github.com/MacHu-GWU/soft_deps-project/actions?query=workflow:CI
+
+.. image:: https://codecov.io/gh/MacHu-GWU/soft_deps-project/branch/main/graph/badge.svg
+    :target: https://codecov.io/gh/MacHu-GWU/soft_deps-project
+
+.. image:: https://img.shields.io/pypi/v/soft-deps.svg
+    :target: https://pypi.python.org/pypi/soft-deps
+
+.. image:: https://img.shields.io/pypi/l/soft-deps.svg
+    :target: https://pypi.python.org/pypi/soft-deps
+
+.. image:: https://img.shields.io/pypi/pyversions/soft-deps.svg
+    :target: https://pypi.python.org/pypi/soft-deps
+
+.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/soft_deps-project/blob/main/release-history.rst
+
+.. image:: https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/soft_deps-project
+
+------
+
+.. image:: https://img.shields.io/badge/Link-API-blue.svg
+    :target: https://soft-deps.readthedocs.io/en/latest/py-modindex.html
+
+.. image:: https://img.shields.io/badge/Link-Install-blue.svg
+    :target: `install`_
+
+.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
+    :target: https://github.com/MacHu-GWU/soft_deps-project
+
+.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
+    :target: https://github.com/MacHu-GWU/soft_deps-project/issues
+
+.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
+    :target: https://github.com/MacHu-GWU/soft_deps-project/issues
+
+.. image:: https://img.shields.io/badge/Link-Download-blue.svg
+    :target: https://pypi.org/pypi/soft-deps#files
+
+
+Welcome to ``soft_deps`` Documentation
+==============================================================================
+.. image:: https://soft-deps.readthedocs.io/en/latest/_static/soft_deps-logo.png
+    :target: https://soft-deps.readthedocs.io/en/latest/
+
+soft-deps is a Python pattern for elegant optional dependency management that prioritizes developer experience over lazy loading. Unlike true lazy imports, soft-deps immediately attempts to import dependencies at module load time - if the dependency is installed, you get the real module with full functionality. If it's missing, you get a helpful proxy object that provides complete IDE type hints and auto-completion, but raises informative error messages only when you actually try to use the missing functionality.
+
+This approach gives you the best of both worlds: seamless development experience with full IDE support when dependencies are available, and graceful degradation with clear installation guidance when they're not, all while maintaining zero code invasiveness in your implementation.
+
+
+Quick Start
+------------------------------------------------------------------------------
+**Why use soft-deps?**
+
+- **For library authors**: Provide optional features without forcing users to install heavy dependencies
+- **For users**: Get full IDE support and autocomplete even for optional dependencies  
+- **For teams**: Graceful degradation with clear error messages instead of cryptic import failures
+
+**When to use soft-deps?**
+
+Use soft-deps when your library has optional features that depend on external packages:
+
+- Data science libraries with optional visualization (matplotlib, plotly)
+- Web frameworks with optional database drivers (psycopg2, pymongo)  
+- CLI tools with optional cloud integrations (boto3, google-cloud)
+- Any library where you want some features to work without heavy dependencies
+
+**How it works:**
+
+Library authors use the soft-deps pattern in their code:
+
+.. code-block:: python
+
+    # your_library.py
+    from soft_deps.api import MissingDependency
+
+    # Try to import optional dependency
+    try:
+        import pandas as pd
+    except ImportError:
+        # Create helpful proxy if missing
+        pd = MissingDependency("pandas", "pip install pandas")
+
+    def export_to_excel(data):
+        """Export data to Excel file (requires pandas)."""
+        # IDE gets full autocomplete here even if pandas not installed
+        # Error only occurs when this line actually executes
+        return pd.DataFrame(data).to_excel("output.xlsx")
+
+Users get seamless experience regardless of what's installed:
+
+.. code-block:: python
+
+    # user_script.py  
+    from your_library import export_to_excel
+
+    # This imports successfully even without pandas installed
+    # IDE provides full autocomplete and type hints
+
+    try:
+        export_to_excel({"col1": [1, 2, 3]})
+    except ImportError as e:
+        print(e)  # "You didn't install pandas. To use DataFrame, pip install pandas"
+
+**The difference:**
+
+.. code-block:: python
+
+    # ❌ Traditional approach - breaks immediately  
+    import pandas as pd  # ImportError if not installed
+    
+    # ❌ Lazy imports - no IDE support
+    def export_data():
+        import pandas as pd  # IDE can't help with autocomplete
+    
+    # ✅ soft-deps - best of both worlds
+    try:
+        import pandas as pd
+    except ImportError:
+        pd = MissingDependency("pandas", "pip install pandas")
+    # IDE gets full support, graceful errors when actually used
+
+
+.. _install:
+
+Install
+------------------------------------------------------------------------------
+
+``soft_deps`` is released on PyPI, so all you need is to:
+
+.. code-block:: console
+
+    $ pip install soft-deps
+
+To upgrade to latest version:
+
+.. code-block:: console
+
+    $ pip install --upgrade soft-deps
+

soft_deps-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+soft_deps/__init__.py,sha256=91jqwa6UIinipz7S0hF5_qpjjB9MUONExbvbLt7UTys,289
+soft_deps/_version.py,sha256=JyS_-kQsLE61QvN-YNEGQYKtbq80QQ787zSo3Hi2T24,566
+soft_deps/api.py,sha256=i85xEuYiS-Ez_qPopY1XSj9B3gyoSFiawlSq5R_34Lw,61
+soft_deps/impl.py,sha256=oRIEryaZ5Ncnj2X3bdsFq6NM7C6i-5oyohDjSMU2vcM,2147
+soft_deps/paths.py,sha256=JH9o7s__FexYpUMuwV7SArCUCdatooOQA1gUYtBm7UY,1226
+soft_deps/vendor/__init__.py,sha256=O9CT1B2F-cVB8elT0EoCJbgkcffjvlmqteqavs4giDg,25
+soft_deps/vendor/pytest_cov_helper.py,sha256=H2BJtFq3bwJHZtt-bxZ1yF9LnXHVDRZZ0NH-OvkRJdE,4063
+soft_deps-0.1.1.dist-info/AUTHORS.rst,sha256=oo38V9AD_y57Ac69mKmiItWquV29SRi2aTCdKQo531A,767
+soft_deps-0.1.1.dist-info/LICENSE.txt,sha256=Vc2EgX0hR-6Qw_RxS1IR-2qllqh4PiqSWFvrdnqZSDU,1084
+soft_deps-0.1.1.dist-info/METADATA,sha256=HFjOHE9k7LqYwW-e7BgynZmEN75nqkp4lUDJ6K1hPUo,7897
+soft_deps-0.1.1.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+soft_deps-0.1.1.dist-info/RECORD,,

soft_deps-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.1
+Root-Is-Purelib: true
+Tag: py3-none-any