Create a new inbuilt library .

Guide to Creating a New Python Submodule

Key Points:

• __all__ in submodule __init__.py is ESSENTIAL - defines public API
• __libs__ in parent __init__.py tracks all submodules
• pyproject.toml only for dependency changes

Quick reference for creating submodules within an existing project.

Table of Contents

1. Project Structure
2. Core Submodule Files
3. Testing Setup
4. Documentation
5. Integration with Parent Project

Project Structure

A submodule should integrate cleanly with your existing project structure:

existing-project/
├── src/
│   └── parent_package/
│       ├── __init__.py
│       ├── submodule/
│       │   ├── __init__.py          # ESSENTIAL: Define __all__ here
│       │   ├── core_module1.py
│       │   ├── core_module2.py
│       │   └── utils/
│       │       ├── __init__.py
│       │       └── helper.py
│       └── other_modules.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_submodule/
│   │   ├── __init__.py
│   │   ├── test_core_module1.py
│   │   └── test_core_module2.py
│   └── test_other_modules.py
└── (other project files)

Key Principles:

• Integrate seamlessly with parent package structure
• Keep submodule self-contained but accessible
• Use meaningful names that follow Python conventions
• ESSENTIAL: Always define __all__ in submodule __init__.py

Core Submodule Files

1. Submodule __init__.py (ESSENTIAL)

Define __all__ to control public API:

"""Submodule description."""
from __future__ import annotations

from .core_module import MainClass, important_function

__all__ = ["MainClass", "important_function"]

2. Parent Package __init__.py

Track submodules with __libs__ and convert/utils/utils.py : LIBRARIES:

# In parent_package/__init__.py
__libs__: list[str] = ["submodule1", "submodule2"]

3. Submodule Module

"""Core functionality."""
from __future__ import annotations
from typing import Any, Optional

class MainClass:
    """Main class."""
    def __init__(self, config: Optional[dict] = None):
        self.config = config or {}
    
    def process(self, data: Any) -> Any:
        """Process data."""
        return processed_data

def important_function(param: str) -> str:
    """Important function."""
    return result

Testing Setup

tests/conftest.py

"""Pytest configuration."""
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent / "src"))

import pytest
from parent_package.submodule import MainClass

@pytest.fixture
def sample_config():
    return {"key1": "value1"}

@pytest.fixture
def instance(sample_config):
    return MainClass(sample_config)

tests/test_submodule/test_core.py

"""Tests."""
import pytest
from parent_package.submodule import MainClass, important_function

class TestMainClass:
    def test_init(self, sample_config):
        instance = MainClass(sample_config)
        assert instance.config == sample_config
    
    def test_process(self, instance):
        result = instance.process("data")
        assert result is not None

def test_function():
    result = important_function("test")
    assert isinstance(result, str)

Documentation

Submodule README

Create src/parent_package/submodule/README.md:

# Submodule Name

Brief description.

## Usage

```python
from parent_package.submodule import MainClass

instance = MainClass()
result = instance.process("data")

## Integration with Parent Project

### 1. Parent Package Integration

Update parent package's `__init__.py`:

```python
# In parent_package/__init__.py
__libs__: list[str] = ["submodule", "other_submodule"]

from . import submodule
from .submodule import MainClass1, important_function1

__all__ = [
    "submodule",
    "MainClass1", 
    "important_function1",
]

2. Dependencies (pyproject.toml)

Only update if you need new dependencies:

# In parent project's pyproject.toml
[project]
dependencies = [
    "existing-dep>=1.0.0",
    "new-submodule-dep>=1.0.0",  # Add only if needed
]

Summary Checklist

When creating a new Python submodule:

Required Files:

• src/parent_package/submodule/__init__.py - ESSENTIAL: Define __all__
• src/parent_package/submodule/core_module.py - Main functionality
• tests/test_submodule/test_core_module.py - Tests

Key Steps:

• Define __all__ in submodule __init__.py (controls public API)
• Update parent __init__.py with __libs__ (tracks submodules)
• Update LIBRARIES in utils.py (for importing it is essential)
• Add dependencies to parent pyproject.toml (if needed)
• Import submodule in parent __init__.py

Best Practices:

• Keep public API minimal
• Use sub-packages for internals
• Write tests
• Follow parent project standards

This guide provides a complete foundation for creating a professional, maintainable Python submodule that integrates seamlessly with your existing project.