Metadata-Version: 2.4
Name: seCore
Version: 2026.7.2
Summary: High-performance secure core framework for scalable, reliable applications
Author-email: Cybernetic Innovations <github@cyberneticinnovations.com>
License: MIT License
        
        Copyright (c) 2025 Cybernetic Innovations
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML~=6.0.3
Requires-Dist: cryptography~=49.0.0
Requires-Dist: loguru~=0.7.3
Requires-Dist: pydantic~=2.13.4
Requires-Dist: pydantic-settings~=2.14.2
Requires-Dist: requests~=2.34.2
Requires-Dist: urllib3~=2.7.0
Requires-Dist: beautifulsoup4~=4.13.5
Requires-Dist: bitflags~=1.2.0
Provides-Extra: dev
Requires-Dist: pytest~=9.1.1; extra == "dev"
Requires-Dist: pytest-cov~=7.1.0; extra == "dev"
Requires-Dist: build~=1.5.1; extra == "dev"
Requires-Dist: twine~=6.2.0; extra == "dev"

# seCore

A high-performance and secure framework for building scalable, reliable applications. seCore provides essential utilities and modules to streamline development, enhance security, and improve code maintainability.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Modules](#core-modules)
  - [Logging](#logging)
  - [Configuration](#configuration)
  - [Encryption](#encryption)
  - [HTTP & REST](#http--rest)
  - [Python Versions](#python-versions)
  - [Project Root](#project-root)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)

## Features

- **🔒 Security-First**: Built-in encryption, secure configuration management, and best-practice defaults
- **⚡ Performance**: Optimized for high-load applications with minimal overhead
- **📦 Modular**: Pick and use only the modules you need
- **📝 Comprehensive Logging**: Structured logging with multiple levels and custom formatting
- **🔧 Configuration Management**: Environment-based settings with validation
- **🌐 HTTP Utilities**: Simplified REST API interactions with robust error handling
- **🐍 Python Version Info**: Easy access to current and historical Python release data

## Installation

Install seCore from PyPI:

```bash
pip install seCore
```

For development dependencies (testing, building):

```bash
pip install seCore[dev]
```

**Requirements**: Python ≥ 3.10

## Quick Start

```python
from seCore import logger, settings, encryption, HttpRest, HttpAction, PyVersions

# Logging
logger.info("Application started")
logger.debug("Debug information")
logger.error("An error occurred")

# Configuration
print(settings)  # Access environment settings

# Encryption
cipher = encryption()
encrypted = cipher.encrypt("Secret message")
decrypted = cipher.decrypt(encrypted)

# HTTP Requests
api = HttpRest()
result, status = api.http_request(HttpAction.GET, "https://api.example.com/data")

# Python Version Info
py_ver = PyVersions()
print(py_ver.versions)  # Current Python versions
print(py_ver.releases)  # Recent releases
```

---

# Core Modules

## Logging

Custom structured logging with multiple log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL).

### Basic Usage

```python
from seCore import logger

logger.debug("Detailed information for developers")
logger.info("General information about program flow")
logger.warning("Something you should look into")
logger.error("An unexpected problem occurred")
logger.critical("A serious error has occurred")
```

### Output Example

```
seCore | DEBUG    | Detailed information for developers
seCore | INFO     | General information about program flow
seCore | WARNING  | Something you should look into
seCore | ERROR    | An unexpected problem occurred
seCore | CRITICAL | A serious error has occurred
```

### Configuration

Set logging level via environment variable `LOG_LEVEL`:
- `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

Customize log format with `LOG_FORMAT` environment variable.

---

## Configuration

Manage application settings from environment variables with validation and defaults.

### Basic Usage

```python
from seCore import settings, settings_not_set

# Access configured settings
print(settings['ENVIRONMENT'])
print(settings['LOG_LEVEL'])
print(settings['PROJECT_ROOT'])

# Check unset required settings
for setting, details in settings_not_set.items():
    print(f"Missing: {setting}")
```

### Common Settings

| Setting | Description | Example |
|---------|-------------|---------|
| `ENVIRONMENT` | Application environment | `Local`, `Development`, `Production` |
| `LOG_LEVEL` | Logging verbosity | `DEBUG`, `INFO`, `WARNING` |
| `LOG_APPNAME` | Application name in logs | `seCore` |
| `PROJECT_ROOT` | Root directory of project | `/path/to/project` |
| `MSSQL_*` | SQL Server configuration | Various |

Custom settings can be added in environment configuration files.

---

## Encryption

Secure encryption and decryption using industry-standard cryptography.

### Basic Usage

```python
from seCore import encryption, logger

cipher = encryption()

# Get encryption key
key = cipher.key.decode()
logger.info(f"Key: {key}")

# Encrypt data
message = "Sensitive information"
encrypted = cipher.encrypt(message).decode()
logger.info(f"Encrypted: {encrypted}")

# Decrypt data
decrypted = cipher.decrypt(encrypted)
logger.info(f"Decrypted: {decrypted}")
```

### Key Features

- **Fernet encryption**: Strong symmetric encryption (AES-128)
- **Key management**: Automatic key generation and retrieval
- **Encoding**: Automatic Base64 encoding/decoding
- **Security**: Cryptographically secure by default

### Use Cases

- Protecting sensitive configuration data
- Encrypting user credentials
- Securing API keys and tokens
- Data privacy in transit

---

## HTTP & REST

Simplified HTTP requests with error handling and support for multiple methods.

### Basic Usage

```python
from seCore import HttpRest, HttpAction

api = HttpRest()

# GET request
result, status = api.http_request(HttpAction.GET, "https://api.example.com/users")
print(f"Status: {status}, Result: {result}")

# POST request
headers = {"Content-Type": "application/json"}
result, status = api.http_request(HttpAction.POST, "https://api.example.com/users", headers)

# PATCH request
result, status = api.http_request(HttpAction.PATCH, "https://api.example.com/users/1", headers)
```

### Supported Methods

- `HttpAction.GET` - Retrieve data
- `HttpAction.POST` - Submit data
- `HttpAction.PUT` - Replace resource
- `HttpAction.PATCH` - Partial update
- `HttpAction.DELETE` - Remove resource

### Error Handling

The API automatically handles common HTTP errors and connection issues. Always check the returned status code:

```python
result, status = api.http_request(HttpAction.GET, url)
if status == 200:
    process_data(result)
else:
    logger.error(f"HTTP Error {status}: {result}")
```

---

## Python Versions

Access information about current and historical Python versions and releases.

### Basic Usage

```python
from seCore import PyVersions
import json

py_ver = PyVersions()

# Get version information
print(json.dumps(py_ver.versions, indent=2))

# Get release information
print(json.dumps(py_ver.releases, indent=2))
```

### Response Structure

**Versions** include:
- `version` - Python version number
- `status` - Release status (bugfix, security, etc.)
- `released` - Release date
- `eos` - End of support date

**Releases** include:
- `version` - Specific release version
- `date` - Release date

### Use Cases

- Check Python version support status
- Plan version upgrades
- Verify end-of-life dates
- Monitor security releases

---

## Project Root

Get the project root directory programmatically.

### Basic Usage

```python
from seCore import projectroot

print(projectroot)  # Absolute path to project root
```

---

# API Reference

## Module Exports

```python
from seCore import (
    __version__,           # Version string
    logger,                # Logger instance
    settings,              # Configuration dictionary
    settings_not_set,      # Unset required settings
    encryption,            # Encryption class
    HttpRest,              # HTTP client class
    HttpAction,            # HTTP method enum
    projectroot,           # Project root path
    PyVersions,            # Python version info class
)
```

### logger

**Type**: `loguru.Logger`

Structured logging instance with standard log levels.

Methods:
- `.debug(message)`
- `.info(message)`
- `.warning(message)`
- `.error(message)`
- `.critical(message)`

### encryption()

**Returns**: Encryption instance

Methods:
- `.encrypt(message: str) -> bytes` - Encrypt plaintext
- `.decrypt(ciphertext: str) -> str` - Decrypt ciphertext
- `.key -> bytes` - Get the encryption key

### HttpRest()

**Returns**: HTTP REST client instance

Methods:
- `.http_request(action: HttpAction, url: str, headers: dict = None) -> tuple` - Make HTTP request

Returns: `(response_body, status_code)`

### HttpAction

**Enum** with values:
- `GET`
- `POST`
- `PUT`
- `PATCH`
- `DELETE`

### PyVersions()

**Returns**: Python version information instance

Properties:
- `.versions -> list[dict]` - Python versions
- `.releases -> list[dict]` - Recent releases

---

## Advanced Usage

### Custom Logging Configuration

Set environment variables to customize logging:

```bash
export LOG_LEVEL=DEBUG
export LOG_APPNAME=myapp
export LOG_FORMAT="{extra[app]} | <level>{level: <8}</level> | {message}"
```

### Environment-Based Configuration

Create environment-specific configuration files and load via:

```python
from seCore import settings
print(settings)  # Loads from environment variables
```

### Multiple HTTP Requests

```python
from seCore import HttpRest, HttpAction

api = HttpRest()
endpoints = [
    (HttpAction.GET, "https://api.example.com/users"),
    (HttpAction.GET, "https://api.example.com/posts"),
    (HttpAction.GET, "https://api.example.com/comments"),
]

for action, url in endpoints:
    result, status = api.http_request(action, url)
    print(f"{url}: {status}")
```

---

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Setup

```bash
pip install -e ".[dev]"
pytest
pytest --cov=seCore
```

---

## License

This project is licensed under the MIT License - see [License.md](License.md) for details.

---

