Python Reference
=================


.. _python_project_filter:

PythonProjectFilter
-------------------

The ``PythonProjectFilter`` class is designed to process and filter Python source files within a project location.
It inherits from the generic ``Filter`` class and uses ``PythonProjectLocation`` as input, ``PythonSourceFile`` as
output, and ``PythonProjectConfig`` for configuration.


.. autoclass:: bauklotz.business.filter.python.project::PythonProjectFilter
   :members:
   :show-inheritance:
   :special-members: __init__


Key Features
~~~~~~~~~~~~
* Filters Python source files based on configurable criteria
* Can ignore special files (those starting with ``__``) based on configuration
* Processes files within a given project location
* Yields individual Python source files that meet the filter criteria

Example Usage
~~~~~~~~~~~~~

.. code-block:: python

   # Create a configuration that ignores special files
   config = PythonProjectConfig(ignore_special_files=True)

   # Initialize the filter
   filter = PythonProjectFilter("python_filter", config)

   # Process a project location
   project_location = PythonProjectLocation("/path/to/project")
   for source_file in filter.process(project_location):
       # Handle each filtered Python source file
       print(source_file.file_name)

Configuration
~~~~~~~~~~~~~
The filter's behavior is controlled by :class:`PythonProjectConfig`, which has the following settings:

* ``ignore_special_files``: When set to ``True``, files starting with ``__`` will be excluded from processing.

See Also
~~~~~~~~
* :class:`PythonProjectConfig`
* :ref:`PythonSourceFile <python_source_file>`
* :ref:`PythonProjectLocation <python_project_location>`


.. _python_source_file:

PythonSourceFile
----------------

The ``PythonSourceFile`` class represents a Python source code file within a project structure. It provides
functionality to access and analyze Python source code files, including their metadata and content.


.. autoclass:: bauklotz.reporting.item.python.project.PythonSourceFile
   :members:
   :show-inheritance:
   :special-members: __init__



Key Features
~~~~~~~~~~~~
* Represents individual Python source files (``.py`` files)
* Provides access to file metadata (name, path, etc.)
* Contains file-specific properties and attributes
* Stores facts and metrics about the Python source file

Example Usage
~~~~~~~~~~~~~

.. code-block:: python

   # Create a Python source file instance
   source_file = PythonSourceFile("/path/to/file.py")

   # Access file properties
   print(source_file.file_name)
   print(source_file.file_path)

   # Access file facts/metrics
   for fact, value in source_file.facts.items():
       print(f"{fact}: {value}")

Properties
~~~~~~~~~~
* ``file_name``: The name of the Python source file
* ``file_path``: The full path to the source file
* ``facts``: A dictionary containing various metrics and information about the file

Methods
~~~~~~~
The class provides various methods to access and manipulate the source file information. See the auto-generated
documentation above for a complete list of available methods.

See Also
~~~~~~~~
* :ref:`PythonProjectLocation <python_project_location>`
* :ref:`PythonProjectFilter <python_project_filter>`
* :ref:`PythonProjectGraph`

Notes
~~~~~
When working with ``PythonSourceFile`` instances, be aware that they are typically created and managed by
the :class:`PythonProjectFilter` during project processing.



.. _python_project_location:

PythonProjectLocation
---------------------

The ``PythonProjectLocation`` class represents a location containing Python project files. It provides functionality to
access and iterate over Python source files within a specified project directory structure.


.. autoclass:: bauklotz.reporting.item.python.project.PythonProjectLocation
   :members:
   :show-inheritance:
   :special-members: __init__



Key Features
~~~~~~~~~~~~
* Represents a Python project directory structure
* Provides access to Python source files within the project
* Supports file iteration and discovery
* Maintains project structure context

Example Usage
~~~~~~~~~~~~~

.. code-block:: python

   # Create a project location instance
   project = PythonProjectLocation("/path/to/python/project")

   # Iterate through Python files in the project
   for python_file in project.files():
       print(f"Found Python file: {python_file.file_name}")

   # Get project directory information
   print(f"Project root: {project.path}")

Properties
~~~~~~~~~~

* ``path``: The root path of the Python project location
* ``files()``: Method that yields Python source files in the project

Methods
~~~~~~~
The class provides methods for accessing and iterating over project files. See the auto-generated documentation above for a complete list of available methods.

See Also
~~~~~~~~

* :ref:`PythonSourceFile <python_source_file>`
* :ref:`PythonProjectFilter <python_project_filter>`
* :class:`PythonProjectGraph`

Notes
~~~~~
``PythonProjectLocation`` is typically used as an input for :class:`PythonProjectFilter` to process and analyze Python projects. It serves as the entry point for project analysis and file discovery.