Metadata-Version: 2.2
Name: bisos.pipreqsPlus
Version: 0.1
Summary: bisos.pipreqs-plus
Author: Mohsen Banan
Author-email: libre@mohsen.1.banan.byname.net
Maintainer: Mohsen Banan
Maintainer-email: libre@mohsen.1.banan.byname.net
License: AGPL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: bisos
Requires-Dist: bisos.b
Requires-Dist: bisos.common
Requires-Dist: bisos.pipreqsPlus
Requires-Dist: setuptools==75.8.0
Requires-Dist: wheel==0.38.4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: summary

==================
bisos.pipreqs-plus
==================

.. contents::
   :depth: 3
..

Overview
========

*bisos.pipreqs-plus* is a thin layer on top of
`pipreqs <https://github.com/bndr/pipreqs>`__ that addresses two of
pipreqs' shortcomings when generating ``requirements.txt`` for
real-world Python projects:

#. **Non-``.py`` Python source files.** pipreqs walks ``*.py`` files
   only. Many projects contain executable Python source under ``bin/``
   with different suffixes (``.cs``, ``.pcs``, ``.mcs``) or no extension
   at all. ``pipreqs-plus`` transparently makes these files visible to
   pipreqs by building a scratch directory of ``.py`` symlinks.
   Detection is automatic: any file whose first line matches a Python
   shebang (``#!.*python*``) is included. An optional ``--extraExts``
   list catches files that lack a shebang.

#. **Namespace-package submodule imports.** When pipreqs encounters
   ``from NS.X import ...`` or ``import NS.X``, it collapses the record
   down to a single ``NS``. For genuine namespace packages where each
   ``NS.X`` is separately published to PyPI (e.g. ``bisos.b``,
   ``bisos.common``, ``bisos.pycs``), this loses information the
   ``requirements.txt`` needs. ``pipreqs-plus`` scans the sources
   independently for ``NS.X``-style imports and appends the two-level
   names to ``requirements.txt``. The bare ``NS`` line from pipreqs is
   preserved.

``bisos.pipreqs-plus`` is intended to be broadly useful — it does not
depend on the BISOS platform for its core function. It is distributed as
a ``bisos-pip`` package because that is the packaging convention its
author uses.

Package Documentation At Github
===============================

The information below is a subset of the full of documentation for this
bisos-pip package. More complete documentation is available at:
https://github.com/bisos-pip/capability-cs

.. _table-of-contents:

Table of Contents TOC
=====================

-  `Overview <#overview>`__
-  `Package Documentation At
   Github <#package-documentation-at-github>`__
-  `Installation <#installation>`__

   -  `Installation With pip <#installation-with-pip>`__
   -  `Installation With pipx <#installation-with-pipx>`__

-  `Usage <#usage>`__

   -  `Minimal invocation <#minimal-invocation>`__
   -  `Full invocation <#full-invocation>`__
   -  `Parameters <#parameters>`__

-  `How it works <#how-it-works>`__
-  `Source code <#source-code>`__

Installation
============

The sources for the ``bisos.pipreqs-plus`` pip package are maintained
at: https://github.com/bisos-pip/pipreqs-plus.

The ``bisos.pipreqs-plus`` pip package is available at PYPI as
https://pypi.org/project/bisos.pipreqs-plus.

You can install ``bisos.pipreqs-plus`` with pip or pipx.

Installation With pip
---------------------

.. code:: bash

   pip install bisos.pipreqs-plus

Installation With pipx
----------------------

For command-line-only use, pipx is a good fit:

.. code:: bash

   pipx install bisos.pipreqs-plus

The following command is made available on ``PATH``:

-  ``pipreqs-plus.cs``

**Prerequisite:** ``pipreqs`` itself must be available on ``PATH`` too.
Recommended:

.. code:: bash

   pipx install pipreqs

Usage
=====

Minimal invocation
------------------

Scan a package source tree and its ``./bin`` directory, write
``./requirements.txt``:

.. code:: bash

   pipreqs-plus.cs -i genRequirements --srcDir=./myPackage

Full invocation
---------------

Every knob explicit:

.. code:: bash

   pipreqs-plus.cs -i genRequirements                       \
       --srcDir=./myPackage                                 \
       --binDir=./bin                                       \
       --outFile=./requirements.txt                         \
       --namespaces="['bisos', 'other']"                    \
       --extraExts="['cs', 'pcs', 'mcs']"                   \
       --pipreqsMode=no-pin

Parameters
----------

+-----------------+-----------+-----------------+-----------------+
| Parameter       | Kind      | Default         | Purpose         |
+=================+===========+=================+=================+
| ``srcDir``      | Mandatory | —               | Package source  |
|                 |           |                 | tree; scanned   |
|                 |           |                 | recursively.    |
+-----------------+-----------+-----------------+-----------------+
| ``binDir``      | Optional  | ``./bin``       | Exec            |
|                 |           |                 | utables/scripts |
|                 |           |                 | dir; scanned    |
|                 |           |                 | top-level only. |
+-----------------+-----------+-----------------+-----------------+
| ``outFile``     | Optional  | ``./req         | Where to write. |
|                 |           | uirements.txt`` |                 |
+-----------------+-----------+-----------------+-----------------+
| ``extraExts``   | Optional  | ``[]``          | Python-literal  |
|                 |           |                 | list of         |
|                 |           |                 | extensions to   |
|                 |           |                 | treat as        |
|                 |           |                 | Python.         |
+-----------------+-----------+-----------------+-----------------+
| ``namespaces``  | Optional  | ``['bisos']``   | Python-literal  |
|                 |           |                 | list of         |
|                 |           |                 | namespace       |
|                 |           |                 | packages to     |
|                 |           |                 | expand.         |
+-----------------+-----------+-----------------+-----------------+
| ``pipreqsMode`` | Optional  | ``"no-pin"``    | Passed through  |
|                 |           |                 | to              |
|                 |           |                 | ``pi            |
|                 |           |                 | preqs --mode``. |
+-----------------+-----------+-----------------+-----------------+

List-valued parameters (``namespaces``, ``extraExts``) accept
Python-literal syntax. Because PyCS (Python Command Service) is
Python-centric, all list values on the command line are Python literals.
Use double-quoted shell strings with single-quoted Python strings
inside:

.. code:: bash

   --namespaces="['bisos', 'other']"
   --extraExts="['cs', 'pcs', 'mcs']"

How it works
============

Given ``srcDir`` and ``binDir``, ``pipreqs-plus.cs`` builds a scratch
directory of ``.py`` symlinks:

-  Files under ``srcDir`` are exposed as-is (they are already ``.py``).
-  Files under ``binDir/*`` (top level only) are included if:

   #. Their extension is ``.py``, or
   #. Their extension (without dot) is in ``extraExts``, or
   #. Their first line matches ``^#!.*\bpython\d*\b`` (a Python
      shebang).

   Included files are symlinked with a ``.py`` suffix so pipreqs will
   scan them.

pipreqs is then invoked against the scratch directory and writes
``outFile``.

For each ``NS`` in ``namespaces``, the scratch directory is scanned
independently for ``from NS.X ...`` and ``import NS.X ...`` statements.
The captured two-level ``NS.X`` names are appended to ``outFile`` and
the file is sort-uniq'd in place.

The scratch directory is removed on exit.

Source code
===========

Source code is written in COMEEGA (https://github.com/bx-blee/comeega);
the primary implementation files are:

-  `file:./bin/pipreqs-plus.cs <./bin/pipreqs-plus.cs>`__ — CLI entry
   point.
-  `file:./bisos/pipreqsPlus/scanner.py <./bisos/pipreqsPlus/scanner.py>`__
   — namespace-import scanner.
-  `file:./bisos/pipreqsPlus/symlinkTree.py <./bisos/pipreqsPlus/symlinkTree.py>`__
   — scratch-tree builder with shebang detection.
