PyFundaments.md

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.

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
• The Role of main.py
• Configuration (.env)
• Installation
• Getting Started
• Module Documentation
• 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

• Validate Dependencies: It checks for all necessary core modules in fundaments/ and exits immediately if any are missing.
• Conditional Environment Loading: It uses the config_handler to load available configuration variables and initializes only the services for which configuration is present.
• 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.
• Graceful Degradation: Services that cannot be initialized are skipped with warnings, allowing applications to run with partial functionality.
• 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)

# 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

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.

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
config_handler.py	Universal configuration loader	config_handler.py.md
encryption.py	Cryptographic routines	encryption.py.md
postgresql.py	Secure, asynchronous database access	postgresql.py.md
user_handler.py	Authentication and identity management	user_handler.py.md
security.py	Central security orchestration layer	security.py.md

---

License

This project is licensed under the Apache 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