# Equipment: The Complete Developer's Manual

> Equipment is a comprehensive scaffolding framework designed to simplify and streamline Python project development. It provides a robust, flexible foundation for projects of any scale, from simple scripts to complex enterprise applications.

---

## 1. Prologue & Design Philosophy

Equipment is built to eliminate the "blank page" problem in Python development. By providing a pre-configured architecture and a set of core services, it allows developers to focus on business logic from minute one.

### Core Design Principles
1. **Developer Experience (DX)**: Minimize boilerplate code and configuration overhead.
2. **Flexibility**: Support various project types (CLI, Web, Background Workers) without being overly opinionated.
3. **Scalability**: Seamlessly transition from a 10-line script to a distributed enterprise system.
4. **Modularity**: Every component (Log, DB, Queue, Storage) is an interchangeable service managed by Dependency Injection.

---

## 2. Installation & Quick Start

### System Requirements
- **Python**: 3.12+ (uses modern type hinting)
- **OS**: Windows, macOS, Linux
- **Package Manager**: pip, pipenv, or poetry

### standard Installation
```bash
pip install equipment
```

### Creating a Project
```bash
equipment new my-app
cd my-app
pip install .
```

### Verifying the Setup
```bash
equipment --version
python main.py
```

---

## 3. Project Directory Structure

Equipment uses a modular directory structure designed for clean separation of concerns.

```text
my-app/
├── app/                  # Application-specific logic
│   ├── __init__.py       # Service registrations (App class)
│   ├── Inspire.py        # Business logic example
│   └── Scheduler.py      # Custom task scheduling definitions
├── config/               # Component-specific configurations
│   ├── app.yaml          # Metadata and environment settings
│   ├── database.yaml     # Connection strings (supports SQLA)
│   ├── log.yaml          # Multi-channel log drivers
│   ├── queue.yaml        # Sync/Redis queue settings
│   └── storage.yaml      # Local/S3 filesystem drivers
├── database/             # persistence layer
│   ├── migrations/       # Alembic version control
│   └── database.sqlite   # Default development database
├── storage/              # Abstract filesystem storage
│   ├── app/              # Local disk root
│   └── logs/             # File-based logs
├── tests/                # Integrated testing framework
│   ├── __init__.py       # TestCase base class with DI support
│   └── test_example.py   # Pytest examples
├── main.py               # Main CLI/Script entry point
├── queues.py             # redis-rq Worker entry point
├── scheduler.py          # Background scheduler entry point
├── web.py                # FastAPI server entry point
└── pyproject.toml        # Dependency and metadata management
```

---

## 4. Dependency Injection (DI)

Equipment implements DI using the `python-dependency-injector` library, specifically the `ThreadSafeSingleton` provider.

### The Architecture
Dependencies are split into two layers:
1. **Library Services**: Core logic provided by the framework (Log, Queue, Database, Storage).
2. **Application Services**: Custom logic defined by the developer in `app/__init__.py`.

### Registering Services
```python
# app/__init__.py
from dependency_injector.providers import ThreadSafeSingleton as Singleton
from equipment import Equipment

class App(Equipment):
    # Registering a custom service
    myservice = Singleton(
        MyService,
        Equipment.log,                  # Injecting library service
        Equipment.config.app.setting    # Injecting config value
    )
```

### Accessing services
```python
from app import app
instance = app()

instance.log().info("Hello")
instance.myservice().do_work()
```

---

## 5. Configuration Management

Equipment supports YAML, JSON, and INI files. Configurations are automatically loaded based on their filenames in the `config/` directory.

### Environment Variable Interpolation
Generic configs can be specialized using the `${VAR:default}` syntax.
```yaml
app:
  name: ${APP_NAME:Equipment}
  env: ${APP_ENV:local}
```

### Core Configuration Files
- `app.yaml`: Global application state.
- `database.yaml`: SQL connection drivers.
- `log.yaml`: Logging channels and formatters (supports JSON).
- `queue.yaml`: Driver selection (`sync` vs `redis`).
- `storage.yaml`: Filesystem driver selection (`local` vs `s3`).

---

## 6. Database Management

Powered by **SQLAlchemy** (ORM) and **Alembic** (Migrations).

### RAW SQL Example
```python
with app.database().engine.connect() as conn:
    conn.execute(app.database().text("UPDATE users SET active=1"))
```

### ORM Example
```python
session = app.database().session()
new_user = User(name="Alice")
session.add(new_user)
session.commit()
```

### Migrations
```bash
cd database/migrations
alembic revision --autogenerate -m "description"
alembic upgrade head
```

---

## 7. Logging System

Supports multiple channels and JSON formatting for production observability.

### Channels
- `stack`: Log to multiple destinations at once.
- `single`: One log file.
- `daily`: Automated rotation.
- `console`: Standard output.
- `sqlite`: Log to a database table.

### Usage
```python
app.log().error("API Failure", extra={"url": "...", "status": 500})
```

---

## 8. Queue & Background Tasks

Equipment abstracts background processing using the `rq` library for Redis and a `sync` driver for development.

### Drivers
- `sync`: Tasks execute immediately (useful for debugging).
- `redis`: Tasks are pushed to Redis and consumed by `queues.py`.

### Enqueuing
```python
app.queue().push(my_function, arg1, arg2)

# Delayed execution
app.queue().push_at(datetime.now() + timedelta(hours=1), my_function)
```

### Starting the Worker
```bash
python queues.py
```

---

## 9. Task Scheduling

Built on the `schedule` library. Definitions live in `app/Scheduler.py`.

### Common Patterns
```python
class Scheduler(Equipment):
    def run(self) -> None:
        self.schedule.every(10).minutes.do(self.my_task)
        self.schedule.every().day.at("00:00").do(self.cleanup)
        super().run()
```

---

## 10. Storage Management

A unified Filesystem API that allows switching between Local disk and Amazon S3 without changing code.

### Supported Methods
- `write(path, data)`
- `read(path)`
- `exists(path)`
- `remove(path)`
- `move(src, dest)`
- `list(directory)`

---

## 11. Testing Framework

Pre-configured `pytest` environment with a `TestCase` base class.

### TestCase Features
- **Auto-context**: Fresh `App` instance for every test.
- **Faker**: Pre-configured data generator (`self.fake`).
- **Isolation**: Automatically sets environment to `testing`.

### Example
```python
from tests import TestCase

class MyTest(TestCase):
    def test_foo(self):
        name = self.fake.name()
        self.app.storage().write("test.txt", name)
        self.assertTrue(self.app.storage().exists("test.txt"))
```

---

## 12. Project Compilation

Utilities for preparing bytecode distributions.

### Bytecode Compilation
```bash
equipment compile dist
```
This converts `.py` to `.pyc`, removes source files, and copies all non-Python assets to the `dist` folder, creating a deployment-ready package.

---

## 13. Web Development (FastAPI)

Integrates seamlessly with FastAPI.

```python
from app import app
from fastapi import FastAPI
from uvicorn import Server, Config

app = app()
web = FastAPI(title=app.config.app.name())

@web.get("/")
async def index():
    return {"quote": app.inspiring().quote()}

if __name__ == "__main__":
    Server(Config(app="web:web", host="0.0.0.0", port=8000)).run()
```