| # PyFundaments: A Secure Python Architecture |
| ##### v. 1.0.1 dev |
|
|
| ## Description |
|
|
| This project, named **PyFundaments**, provides a robust and secure Python architecture. Its core mission is not to be a monolithic framework, but to establish a layered, modular foundation—or "fundament"—of essential services. This structure ensures that every application starts on a verified and secure base, with a focus on stability, code clarity, and a security-first mindset from the ground up. |
|
|
| > [!NOTE] |
| > you must create your app/bot in app/* or you get an error! Than uncoment |
| > ``` |
| >from app.app import start_application |
| >await start_application(fundaments) |
| >``` |
| > in main.py |
| |
| |
| |
| ----- |
| |
| ## Table of Contents |
| |
| - [Project Structure](#project-structure) |
| - [The Role of `main.py`](#the-role-of-mainpy) |
| - [Configuration (`.env`)](#configuration-env) |
| - [Installation](#installation) |
| - [Getting Started](#getting-started) |
| - [Module Documentation](#module-documentation) |
| - [Notes](#notes) |
| |
| ----- |
| |
| ## Project Structure |
| |
| ``` |
|
|
| ├── main.py # run main! |
| ├── README.md |
| ├── requirements.txt |
| ├── .gitignore |
| ├── .env.example |
| ├── app/ |
| │ └── ... |
| │ └── app.py # sandboxed app run! |
| │ └── tools.py |
| │ └── provider.py |
| │ └── models.py |
| │ └── db_sync.py |
| |
| ├── fundaments/ # do not touch! |
| │ ├── access_control.py |
| │ ├── config_handler.py |
| │ ├── encryption.py |
| │ ├── postgresql.py |
| │ ├── security.py |
| │ └── user_handler.py |
| └── docs/ |
| ├── access_control.py.md |
| ├── encryption.py.md |
| ├── postgresql.py.md |
| ├── security.py.md |
| └── user_handler.py.md |
| |
| ``` |
| ----- |
|
|
| ## The Role of `main.py` |
|
|
| `main.py` is the **only entry point** and acts as the first line of defense for the application. |
|
|
| ### Responsibilities |
|
|
| - [x] **Validate Dependencies**: It checks for all necessary core modules in `fundaments/` and exits immediately if any are missing. |
| - [x] **Conditional Environment Loading**: It uses the `config_handler` to load available configuration variables and initializes only the services for which configuration is present. |
| - [x] **Initialize Services**: It creates instances of available services (PostgreSQL, encryption, access control, user handling) based on environment configuration, collecting them into a single service dictionary. |
| - [x] **Graceful Degradation**: Services that cannot be initialized are skipped with warnings, allowing applications to run with partial functionality. |
| - [x] **Decouple App Logic**: It hands off the prepared and verified services to `app/app.py`, allowing the main application to focus purely on its business logic without worrying about low-level setup. |
|
|
| ----- |
|
|
| ## Configuration (`.env`) |
|
|
| Application settings are managed using a `.env` file. **Never commit this file to version control.** |
|
|
| The framework uses **conditional loading** - only services with available configuration are initialized. This allows different application types to use only what they need. |
|
|
| A `.env.example` file is provided to show available variables. Create a copy named `.env` and configure only what your application requires. |
|
|
| ### Core Configuration (Optional based on app type) |
|
|
| ```text |
| # Database connection (required only for database-using apps) |
| DATABASE_URL="postgresql://user:password@host:port/database?sslmode=require" |
| |
| # Encryption keys (required only for apps using encryption) |
| MASTER_ENCRYPTION_KEY="your_256_bit_key_here" |
| PERSISTENT_ENCRYPTION_SALT="your_unique_salt_here" |
| |
| # Logging configuration (optional) |
| LOG_LEVEL="INFO" |
| LOG_TO_TMP="false" |
| ENABLE_PUBLIC_LOGS="true" |
| ``` |
|
|
| ### Application Examples |
|
|
| **Discord Bot:** Only needs `BOT_TOKEN`, no database or encryption required. |
| **ML Pipeline:** Only needs `DATABASE_URL` for data access. |
| **Web Application:** May need all services for full functionality. |
|
|
| ----- |
|
|
| ## Installation |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| ----- |
|
|
| ## Getting Started |
|
|
| 1. **Configure**: Create your `.env` file from the `.env.example` and set only the variables your application type requires. |
| 2. **Run**: Execute the `main.py` script to start the application. |
|
|
| ```bash |
| python main.py |
| ``` |
|
|
| The framework will automatically detect available configuration and load only the necessary services. |
|
|
| ----- |
|
|
| ## Module Documentation |
|
|
| Each security-relevant core module is documented in the `docs/` directory: |
|
|
| | Module | Description | Documentation | |
| | ------------------- | ---------------------------------------- | -------------------------------------------------| |
| | `access_control.py` | Role-based access management | [access\_control.py.md](docs/access_control.py.md)| |
| | `config_handler.py` | Universal configuration loader | [config\_handler.py.md](docs/config_handler.py.md)| |
| | `encryption.py` | Cryptographic routines | [encryption.py.md](docs/encryption.py.md) | |
| | `postgresql.py` | Secure, asynchronous database access | [postgresql.py.md](docs/postgresql.py.md) | |
| | `user_handler.py` | Authentication and identity management | [user\_handler.py.md](docs/user_handler.py.md) | |
| | `security.py` | Central security orchestration layer | [security.py.md](docs/security.py.md) | |
|
|
| ----- |
|
|
| ## License |
|
|
| This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). |
|
|
| ### Section 4: Additional Restrictions and Ethical Use Policy |
|
|
| This project is released under the permissive Apache 2.0 License, which is intended to provide broad freedom for use and modification. |
| However, in the interest of fostering a safe and responsible community, we include the following **mandatory ethical use restrictions**: |
|
|
| Use of this project (or derivatives) is **strictly prohibited** for purposes that: |
|
|
| - **Promote Hatred or Discrimination** |
| Includes hate speech, incitement to violence, or discrimination based on race, religion, gender, orientation, etc. |
| |
| - **Facilitate Illegal Activities** |
| Use to conduct or support criminal activity is forbidden. |
| |
| - **Spread Malicious Content** |
| This includes pornography, malware, spyware, or other harmful payloads. |
| |
| We believe that freedom in development must be coupled with responsibility. |
| **Violation of these terms constitutes a breach of license and will trigger takedown actions** including legal and technical responses. |
|
|
| *Volkan Kücükbudak* |
|
|
| ----- |
|
|
| ## Credits |
|
|
| - Developed and maintained by the PyFundaments project. |
| - Core components inspired by best practices in modular app architecture and OWASP security principles. |
| - Third-party libraries are credited in their respective module docs and comply with open-source terms. |
|
|
| ----- |
|
|
| ## Notes |
|
|
| Security-first by design. |
| If one piece is missing or unsafe — the app does not run. |
| Zero tolerance for guesswork. |
| |
| > Give a ⭐ if you find the structure helpful. |
|
|
|
|
| ## Changelog |
| ###### Version 1.0.0 -> 1.0.1 |
| ### PyFundaments Refactoring |
|
|
| #### Modified Files |
|
|
| **1. main.py - Conditional Service Loading** |
| - **Added:** Environment-based conditional service initialization |
| - **Added:** Graceful fallback when services can't be initialized (warning instead of crash) |
| - **Added:** Conditional logging configuration (LOG_LEVEL, LOG_TO_TMP, ENABLE_PUBLIC_LOGS) |
| - **Added:** Smart dependency management (access_control & user_handler only load if database available) |
| - **Added:** Safe shutdown (only close DB pool if it was initialized) |
| - **Result:** Framework now supports partial service loading for different app types |
| |
| **2. app/app.py - Proper Service Injection** |
| - **Removed:** Direct service imports and instantiation |
| - **Added:** Services received as parameter from main.py |
| - **Modified:** start_application() now takes fundaments dictionary as parameter |
| - **Added:** Conditional service usage based on what main.py provides |
| - **Added:** Examples for different app types (database-only, database-free modes) |
| - **Result:** Clean separation - main.py handles initialization, app.py uses services |
|
|
| **3. fundaments/config_handler.py - Universal Configuration Loader** |
| - **Removed:** REQUIRED_KEYS validation (moved to main.py) |
| - **Modified:** Now loads ALL environment variables without validation |
| - **Added:** Helper methods: get_bool(), get_int(), has(), get_all() |
| - **Added:** Safe defaults and type conversion |
| - **Result:** Config handler never needs updates, works with any ENV variables |
| |
| **4. .env.example - Conditional Configuration Template** |
| - **Added:** Clear separation between core and optional dependencies |
| - **Added:** Logging configuration options |
| - **Added:** App-specific configuration examples (Discord, ML, Web) |
| - **Added:** Comments explaining when to use each option |
| - **Result:** Users only configure what they need, no unused variables |
| |
| #### Architecture Improvements |
| - **Conditional Loading:** Framework only loads needed services based on available ENV vars |
| - **Merge-Safe Structure:** User code (app/, config_handler.py) protected from framework updates |
| - **Zero Breaking Changes:** Updates only affect fundaments/ directory |
| - **Enterprise-Level Merging:** Community can safely pull framework updates</document_content></document> |
|
|
