Alibrown commited on
Commit
a7ddb19
·
verified ·
1 Parent(s): 404db42

Delete PyFundaments.md

Browse files
Files changed (1) hide show
  1. PyFundaments.md +0 -232
PyFundaments.md DELETED
@@ -1,232 +0,0 @@
1
- # PyFundaments: A Secure Python Architecture
2
- ##### v. 1.0.1 dev
3
-
4
- ## Description
5
-
6
- 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.
7
-
8
- > [!NOTE]
9
- > you must create your app/bot in app/* or you get an error! Than uncoment
10
- > ```
11
- >from app.app import start_application
12
- >await start_application(fundaments)
13
- >```
14
- > in main.py
15
-
16
-
17
-
18
- -----
19
-
20
- ## Table of Contents
21
-
22
- - [Project Structure](#project-structure)
23
- - [The Role of `main.py`](#the-role-of-mainpy)
24
- - [Configuration (`.env`)](#configuration-env)
25
- - [Installation](#installation)
26
- - [Getting Started](#getting-started)
27
- - [Module Documentation](#module-documentation)
28
- - [Notes](#notes)
29
-
30
- -----
31
-
32
- ## Project Structure
33
-
34
- ```
35
-
36
- ├── main.py # run main!
37
- ├── README.md
38
- ├── requirements.txt
39
- ├── .gitignore
40
- ├── .env.example
41
- ├── app/
42
- │ └── ...
43
- │ └── app.py # sandboxed app run!
44
- │ └── tools.py
45
- │ └── provider.py
46
- │ └── models.py
47
- │ └── db_sync.py
48
-
49
- ├── fundaments/ # do not touch!
50
- │ ├── access_control.py
51
- │ ├── config_handler.py
52
- │ ├── encryption.py
53
- │ ├── postgresql.py
54
- │ ├── security.py
55
- │ └── user_handler.py
56
- └── docs/
57
- ├── access_control.py.md
58
- ├── encryption.py.md
59
- ├── postgresql.py.md
60
- ├── security.py.md
61
- └── user_handler.py.md
62
-
63
- ```
64
- -----
65
-
66
- ## The Role of `main.py`
67
-
68
- `main.py` is the **only entry point** and acts as the first line of defense for the application.
69
-
70
- ### Responsibilities
71
-
72
- - [x] **Validate Dependencies**: It checks for all necessary core modules in `fundaments/` and exits immediately if any are missing.
73
- - [x] **Conditional Environment Loading**: It uses the `config_handler` to load available configuration variables and initializes only the services for which configuration is present.
74
- - [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.
75
- - [x] **Graceful Degradation**: Services that cannot be initialized are skipped with warnings, allowing applications to run with partial functionality.
76
- - [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.
77
-
78
- -----
79
-
80
- ## Configuration (`.env`)
81
-
82
- Application settings are managed using a `.env` file. **Never commit this file to version control.**
83
-
84
- The framework uses **conditional loading** - only services with available configuration are initialized. This allows different application types to use only what they need.
85
-
86
- A `.env.example` file is provided to show available variables. Create a copy named `.env` and configure only what your application requires.
87
-
88
- ### Core Configuration (Optional based on app type)
89
-
90
- ```text
91
- # Database connection (required only for database-using apps)
92
- DATABASE_URL="postgresql://user:password@host:port/database?sslmode=require"
93
-
94
- # Encryption keys (required only for apps using encryption)
95
- MASTER_ENCRYPTION_KEY="your_256_bit_key_here"
96
- PERSISTENT_ENCRYPTION_SALT="your_unique_salt_here"
97
-
98
- # Logging configuration (optional)
99
- LOG_LEVEL="INFO"
100
- LOG_TO_TMP="false"
101
- ENABLE_PUBLIC_LOGS="true"
102
- ```
103
-
104
- ### Application Examples
105
-
106
- **Discord Bot:** Only needs `BOT_TOKEN`, no database or encryption required.
107
- **ML Pipeline:** Only needs `DATABASE_URL` for data access.
108
- **Web Application:** May need all services for full functionality.
109
-
110
- -----
111
-
112
- ## Installation
113
-
114
- ```bash
115
- pip install -r requirements.txt
116
- ```
117
-
118
- -----
119
-
120
- ## Getting Started
121
-
122
- 1. **Configure**: Create your `.env` file from the `.env.example` and set only the variables your application type requires.
123
- 2. **Run**: Execute the `main.py` script to start the application.
124
-
125
- ```bash
126
- python main.py
127
- ```
128
-
129
- The framework will automatically detect available configuration and load only the necessary services.
130
-
131
- -----
132
-
133
- ## Module Documentation
134
-
135
- Each security-relevant core module is documented in the `docs/` directory:
136
-
137
- | Module | Description | Documentation |
138
- | ------------------- | ---------------------------------------- | -------------------------------------------------|
139
- | `access_control.py` | Role-based access management | [access\_control.py.md](docs/access_control.py.md)|
140
- | `config_handler.py` | Universal configuration loader | [config\_handler.py.md](docs/config_handler.py.md)|
141
- | `encryption.py` | Cryptographic routines | [encryption.py.md](docs/encryption.py.md) |
142
- | `postgresql.py` | Secure, asynchronous database access | [postgresql.py.md](docs/postgresql.py.md) |
143
- | `user_handler.py` | Authentication and identity management | [user\_handler.py.md](docs/user_handler.py.md) |
144
- | `security.py` | Central security orchestration layer | [security.py.md](docs/security.py.md) |
145
-
146
- -----
147
-
148
- ## License
149
-
150
- This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
151
-
152
- ### Section 4: Additional Restrictions and Ethical Use Policy
153
-
154
- This project is released under the permissive Apache 2.0 License, which is intended to provide broad freedom for use and modification.
155
- However, in the interest of fostering a safe and responsible community, we include the following **mandatory ethical use restrictions**:
156
-
157
- Use of this project (or derivatives) is **strictly prohibited** for purposes that:
158
-
159
- - **Promote Hatred or Discrimination**
160
- Includes hate speech, incitement to violence, or discrimination based on race, religion, gender, orientation, etc.
161
-
162
- - **Facilitate Illegal Activities**
163
- Use to conduct or support criminal activity is forbidden.
164
-
165
- - **Spread Malicious Content**
166
- This includes pornography, malware, spyware, or other harmful payloads.
167
-
168
- We believe that freedom in development must be coupled with responsibility.
169
- **Violation of these terms constitutes a breach of license and will trigger takedown actions** including legal and technical responses.
170
-
171
- *Volkan Kücükbudak*
172
-
173
- -----
174
-
175
- ## Credits
176
-
177
- - Developed and maintained by the PyFundaments project.
178
- - Core components inspired by best practices in modular app architecture and OWASP security principles.
179
- - Third-party libraries are credited in their respective module docs and comply with open-source terms.
180
-
181
- -----
182
-
183
- ## Notes
184
-
185
- Security-first by design.
186
- If one piece is missing or unsafe — the app does not run.
187
- Zero tolerance for guesswork.
188
-
189
- > Give a ⭐ if you find the structure helpful.
190
-
191
-
192
- ## Changelog
193
- ###### Version 1.0.0 -> 1.0.1
194
- ### PyFundaments Refactoring
195
-
196
- #### Modified Files
197
-
198
- **1. main.py - Conditional Service Loading**
199
- - **Added:** Environment-based conditional service initialization
200
- - **Added:** Graceful fallback when services can't be initialized (warning instead of crash)
201
- - **Added:** Conditional logging configuration (LOG_LEVEL, LOG_TO_TMP, ENABLE_PUBLIC_LOGS)
202
- - **Added:** Smart dependency management (access_control & user_handler only load if database available)
203
- - **Added:** Safe shutdown (only close DB pool if it was initialized)
204
- - **Result:** Framework now supports partial service loading for different app types
205
-
206
- **2. app/app.py - Proper Service Injection**
207
- - **Removed:** Direct service imports and instantiation
208
- - **Added:** Services received as parameter from main.py
209
- - **Modified:** start_application() now takes fundaments dictionary as parameter
210
- - **Added:** Conditional service usage based on what main.py provides
211
- - **Added:** Examples for different app types (database-only, database-free modes)
212
- - **Result:** Clean separation - main.py handles initialization, app.py uses services
213
-
214
- **3. fundaments/config_handler.py - Universal Configuration Loader**
215
- - **Removed:** REQUIRED_KEYS validation (moved to main.py)
216
- - **Modified:** Now loads ALL environment variables without validation
217
- - **Added:** Helper methods: get_bool(), get_int(), has(), get_all()
218
- - **Added:** Safe defaults and type conversion
219
- - **Result:** Config handler never needs updates, works with any ENV variables
220
-
221
- **4. .env.example - Conditional Configuration Template**
222
- - **Added:** Clear separation between core and optional dependencies
223
- - **Added:** Logging configuration options
224
- - **Added:** App-specific configuration examples (Discord, ML, Web)
225
- - **Added:** Comments explaining when to use each option
226
- - **Result:** Users only configure what they need, no unused variables
227
-
228
- #### Architecture Improvements
229
- - **Conditional Loading:** Framework only loads needed services based on available ENV vars
230
- - **Merge-Safe Structure:** User code (app/, config_handler.py) protected from framework updates
231
- - **Zero Breaking Changes:** Updates only affect fundaments/ directory
232
- - **Enterprise-Level Merging:** Community can safely pull framework updates</document_content></document>