picage 1.0.0

A lightweight utility library providing an object-oriented interface for inspecting Python package and module structure.

---

Welcome to picage Documentation

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

>>> 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

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

$ pip install picage

To upgrade to latest version:

$ pip install --upgrade picage