Metadata-Version: 2.4
Name: picage
Version: 1.0.0
Summary: A lightweight utility library providing an object-oriented interface for inspecting Python package and module structure.
Author-email: Sanhe Hu <husanhe@email.com>
Maintainer-email: Sanhe Hu <husanhe@email.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MacHu-GWU/picage-project
Project-URL: Documentation, https://picage.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/MacHu-GWU/picage-project
Project-URL: Issues, https://github.com/MacHu-GWU/picage-project/issues
Project-URL: Changelog, https://github.com/MacHu-GWU/picage-project/blob/main/release-history.rst
Project-URL: Download, https://pypi.org/pypi/picage#files
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/x-rst
License-File: AUTHORS.rst
Provides-Extra: dev
Requires-Dist: rich<14.0.0,>=13.8.1; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest<9.0.0,>=8.2.2; extra == "test"
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == "test"
Provides-Extra: doc
Requires-Dist: Sphinx<8.0.0,>=7.4.7; extra == "doc"
Requires-Dist: sphinx-copybutton<1.0.0,>=0.5.2; extra == "doc"
Requires-Dist: sphinx-design<1.0.0,>=0.6.1; extra == "doc"
Requires-Dist: sphinx-jinja<3.0.0,>=2.0.2; extra == "doc"
Requires-Dist: furo==2024.8.6; extra == "doc"
Requires-Dist: pygments<3.0.0,>=2.18.0; extra == "doc"
Requires-Dist: ipython<8.19.0,>=8.18.1; extra == "doc"
Requires-Dist: nbsphinx<1.0.0,>=0.8.12; extra == "doc"
Requires-Dist: rstobj==1.2.1; extra == "doc"
Requires-Dist: docfly==3.0.0; extra == "doc"
Provides-Extra: mise
Requires-Dist: PyGithub<3.0.0,>=2.8.0; extra == "mise"
Requires-Dist: httpx<1.0.0,>=0.28.0; extra == "mise"
Requires-Dist: tomli<3.0.0,>=2.0.0; python_version < "3.11" and extra == "mise"
Dynamic: license-file


.. image:: https://readthedocs.org/projects/picage/badge/?version=latest
    :target: https://picage.readthedocs.io/en/latest/
    :alt: Documentation Status

.. image:: https://github.com/MacHu-GWU/picage-project/actions/workflows/main.yml/badge.svg
    :target: https://github.com/MacHu-GWU/picage-project/actions?query=workflow:CI

.. image:: https://codecov.io/gh/MacHu-GWU/picage-project/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/MacHu-GWU/picage-project

.. image:: https://img.shields.io/pypi/v/picage.svg
    :target: https://pypi.python.org/pypi/picage

.. image:: https://img.shields.io/pypi/l/picage.svg
    :target: https://pypi.python.org/pypi/picage

.. image:: https://img.shields.io/pypi/pyversions/picage.svg
    :target: https://pypi.python.org/pypi/picage

.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
    :target: https://github.com/MacHu-GWU/picage-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/picage-project

------

.. image:: https://img.shields.io/badge/Link-API-blue.svg
    :target: https://picage.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/picage-project

.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
    :target: https://github.com/MacHu-GWU/picage-project/issues

.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
    :target: https://github.com/MacHu-GWU/picage-project/issues

.. image:: https://img.shields.io/badge/Link-Download-blue.svg
    :target: https://pypi.org/pypi/picage#files


Welcome to ``picage`` Documentation
==============================================================================
.. image:: https://picage.readthedocs.io/en/latest/_static/picage-logo.png
    :target: https://picage.readthedocs.io/en/latest/

``picage`` is a lightweight utility library that provides an object-oriented interface for inspecting Python package and module structure. Given any installed package name, it automatically locates the source code on the current Python import path and lets you explore its structure. You can access:

- fully qualified name and short name of any package or module
- parent package, sub-packages, and sub-modules
- recursively walk through all sub-packages and sub-modules
- pretty-print the entire package tree

``picage`` supports all common installation formats including flat dist-info/wheel installs, legacy egg-link editable installs, PEP 660 editable installs (both path-insertion and custom-finder strategies), and legacy egg-directory installs.


Usage
------------------------------------------------------------------------------

.. code-block:: python

    >>> from picage.api import Package

    >>> pkg = Package("requests")
    >>> pkg
    Package(name='requests', path='/.../site-packages/requests')

    >>> print(pkg)
    Package(
        name='requests',
        path='/.../site-packages/requests',
        sub_packages=[...],
        sub_modules=['adapters', 'api', 'auth', ...],
    )

    # Access sub-packages and sub-modules
    >>> for name, sub_pkg in pkg.sub_packages.items():
    ...     print(name, sub_pkg.fullname)

    >>> for name, mod in pkg.sub_modules.items():
    ...     print(name, mod.fullname)

    # Use dot notation to access nested children
    >>> mod = pkg["api"]              # direct child module
    >>> deep = pkg["commands.install"]  # dot notation for deeper access

    # Walk through the entire package tree
    >>> for node, parent, sub_pkgs, sub_mods in pkg.walk():
    ...     print(node.fullname)

    # Include leaf modules in the walk
    >>> for node, parent, sub_pkgs, sub_mods in pkg.walk(pkg_only=False):
    ...     print(node.fullname)

    # Navigate the parent chain
    >>> child = pkg["utils"]
    >>> child.parent is pkg
    True
    >>> pkg.parent is None
    True

    # Pretty-print the package tree
    >>> pkg.pprint()
    /.../site-packages
    |-- requests (requests)
        |-- ...


.. _install:

Install
------------------------------------------------------------------------------

``picage`` is released on PyPI, so all you need is:

.. code-block:: console

    $ pip install picage

To upgrade to latest version:

.. code-block:: console

    $ pip install --upgrade picage
