blackant-sdk 1.0.2__tar.gz

blackant_sdk-1.0.2/MANIFEST.in

@@ -0,0 +1,35 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include requirements.txt
+include requirements-dev.txt
+include requirements.debug.txt
+include pyproject.toml
+include setup.py
+include _version.py
+
+recursive-include src *.py
+recursive-include docs *.rst *.md *.py Makefile
+recursive-include config *.yml *.yaml *.json
+recursive-include examples *.py *.md *.yml *.yaml
+recursive-include test *.py
+
+exclude .gitignore
+exclude .gitlab-ci.yml
+exclude docker-compose*.yml
+exclude Dockerfile
+exclude docker-entrypoint.sh
+exclude .dockerignore
+exclude build_docs.sh
+exclude publish.sh
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .DS_Store
+recursive-exclude * *.so
+recursive-exclude .git *
+recursive-exclude .venv *
+recursive-exclude .pytest_cache *
+recursive-exclude htmlcov *
+recursive-exclude dist *
+recursive-exclude build *

blackant_sdk-1.0.2/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: blackant-sdk
+Version: 1.0.2
+Summary: Python SDK for Docker operations with automatic authentication through BlackAnt platform
+Author-email: Balázs Milán <milan.balazs@uni-obuda.hu>
+Maintainer-email: BlackAnt Development Team <dev@blackant.app>
+License: Proprietary - Óbudai Egyetem
+Project-URL: Homepage, https://env.blackant.app/systemdevelopers/blackant_sdk
+Project-URL: Documentation, https://docs.blackant.app
+Project-URL: Repository, https://env.blackant.app/systemdevelopers/blackant_sdk
+Project-URL: Bug Tracker, https://env.blackant.app/systemdevelopers/blackant_sdk/-/issues
+Keywords: docker,sdk,authentication,blackant,container,orchestration,swarm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: flask>=2.3.2
+Requires-Dist: flask-restful>=0.3.10
+Requires-Dist: waitress>=2.1.2
+Requires-Dist: minio>=6.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: docker>=4.4.3
+Requires-Dist: urllib3<2.0
+Requires-Dist: gunicorn>=21.2.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: python-keycloak>=3.0.0
+Requires-Dist: PyJWT>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: sphinx>=5.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=5.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
+
+# Python REST API docker template
+
+A simple template to implement REST APIs using Python Flask & docker.
+
+## Build arguments
+
+### INSTALL_DEBUG_TOOLS
+
+If it's set to True, ptvsd is installed during build to be able to do live debugging.
+
+## Environment variables
+
+### CALCULATION_NAME
+
+Name of the calculation. Mandatory parameter.
+
+### SERVER_PORT
+
+Port which on the server runs. Default: 5000
+
+### DEBUG_MODE
+
+A switch to select between debug and release mode. If it is set to True, a Flask server will be started in debug mode and a ptvsd server. Otherwise, it is served using gevent production server. Default: False
+
+### OBJECT_STORAGE_URL
+
+Url for the object storage. Mandatory if the code uses object storage.
+
+### OBJECT_STORAGE_ACCESS_KEY
+
+Public key for the object storage.
+
+### OBJECT_STORAGE_SECRET_KEY
+
+Private key for the object storage.
+
+### SCHEDULER_URL
+
+Callback url of the scheduler.
+
+## Commands
+
+### Build
+
+```sh
+docker-compose build
+```
+
+### Run
+
+```sh
+docker-compose up
+```
+
+### Create task
+
+You can use the tools/send_request.py script to send a simple request to the calculation container.
+
+### Debug
+
+If you use Visual Studio Code, there is a debug configuration called Python: Remote Attach which will start a debug session and connect to your running container.
+
+## Documentation
+
+Full HTML and PDF documentation can be generated from any revision using the generate_documentation job in the CI.
+After the job have run successfully, the artifacts are stored for one day.
+If it's necessary it can be rerun any time.
+
+
+......

blackant_sdk-1.0.2/README.md

@@ -0,0 +1,70 @@
+# Python REST API docker template
+
+A simple template to implement REST APIs using Python Flask & docker.
+
+## Build arguments
+
+### INSTALL_DEBUG_TOOLS
+
+If it's set to True, ptvsd is installed during build to be able to do live debugging.
+
+## Environment variables
+
+### CALCULATION_NAME
+
+Name of the calculation. Mandatory parameter.
+
+### SERVER_PORT
+
+Port which on the server runs. Default: 5000
+
+### DEBUG_MODE
+
+A switch to select between debug and release mode. If it is set to True, a Flask server will be started in debug mode and a ptvsd server. Otherwise, it is served using gevent production server. Default: False
+
+### OBJECT_STORAGE_URL
+
+Url for the object storage. Mandatory if the code uses object storage.
+
+### OBJECT_STORAGE_ACCESS_KEY
+
+Public key for the object storage.
+
+### OBJECT_STORAGE_SECRET_KEY
+
+Private key for the object storage.
+
+### SCHEDULER_URL
+
+Callback url of the scheduler.
+
+## Commands
+
+### Build
+
+```sh
+docker-compose build
+```
+
+### Run
+
+```sh
+docker-compose up
+```
+
+### Create task
+
+You can use the tools/send_request.py script to send a simple request to the calculation container.
+
+### Debug
+
+If you use Visual Studio Code, there is a debug configuration called Python: Remote Attach which will start a debug session and connect to your running container.
+
+## Documentation
+
+Full HTML and PDF documentation can be generated from any revision using the generate_documentation job in the CI.
+After the job have run successfully, the artifacts are stored for one day.
+If it's necessary it can be rerun any time.
+
+
+......

blackant_sdk-1.0.2/_version.py

@@ -0,0 +1,4 @@
+"""Version information for BlackAnt SDK"""
+
+__version__ = "1.0.0"
+__version_info__ = (1, 0, 0)

blackant_sdk-1.0.2/docs/Makefile

@@ -0,0 +1,17 @@
+
+
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

blackant_sdk-1.0.2/docs/source/conf.py

@@ -0,0 +1,64 @@
+# Configuration file for the Sphinx documentation builder.
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../src'))
+
+
+project = 'BlackAnt SDK'
+copyright = '2025, BlackAnt Team'
+author = 'BlackAnt Team'
+release = '1.0.0'
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.intersphinx',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+language = 'en'
+
+# Napoleon settings for Google style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+# Autodoc settings
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}
+
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# -- Options for intersphinx extension ---------------------------------------
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}
+
+# -- Options for todo extension ----------------------------------------------
+todo_include_todos = True

blackant_sdk-1.0.2/docs/source/index.rst

@@ -0,0 +1,273 @@
+BlackAnt SDK Documentation
+==========================
+
+Welcome to the BlackAnt SDK documentation. BlackAnt SDK is an enterprise-grade Python framework
+for building distributed, containerized applications with comprehensive Docker integration,
+secure authentication, and high-performance HTTP operations.
+
+The SDK provides a complete toolkit for modern microservice architectures, including service
+discovery, configuration management, logging, and monitoring capabilities.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Core Modules:
+
+   modules/blackant
+   modules/auth
+   modules/docker
+   modules/http
+   modules/api
+   modules/services
+   modules/config
+   modules/utils
+   modules/patterns
+
+Key Features
+============
+
+**Authentication & Security**
+   - OAuth 2.0 / OpenID Connect integration with Keycloak
+   - Automatic token refresh and lifecycle management
+   - Thread-safe credential storage
+   - Admin API access for user management
+
+**Docker Integration**
+   - Full Docker Engine API support
+   - Docker Swarm orchestration capabilities
+   - Container lifecycle management
+   - Image building and registry operations
+
+**HTTP Client**
+   - High-performance HTTP client with connection pooling
+   - Automatic retry mechanisms with exponential backoff
+   - Built-in authentication token injection
+   - Comprehensive error handling and logging
+
+**Service Management**
+   - Service discovery and registration
+   - Health monitoring and automatic recovery
+   - Namespace-based multi-tenancy
+   - Load balancing and traffic routing
+
+**Configuration**
+   - Multi-source configuration loading (YAML, environment, CLI)
+   - Runtime validation and type checking
+   - Environment-specific profiles
+   - Secure credential management
+
+Installation
+============
+
+Install the BlackAnt SDK using pip::
+
+   pip install blackant-sdk
+
+Or install from source::
+
+   git clone https://github.com/your-org/blackant-sdk.git
+   cd blackant-sdk
+   pip install -e .
+
+Quick Start Guide
+=================
+
+Authentication
+--------------
+
+Authenticate with the BlackAnt platform using your credentials::
+
+   from blackant.auth.blackant_auth import BlackAntAuth
+
+   # Initialize authentication
+   auth = BlackAntAuth(
+       user="your_username",
+       password="your_password",
+       login_url="https://your-blackant-instance.com/api/auth/login"
+   )
+
+   # Get access token
+   token = auth.get_token()
+   print(f"Authenticated successfully: {token[:30]}...")
+
+Docker Operations
+-----------------
+
+Manage Docker containers and services::
+
+   from blackant.docker.client import BlackAntDockerClient
+
+   # Initialize Docker client with authentication
+   docker_client = BlackAntDockerClient(
+       auth=auth,
+       base_url="https://your-blackant-instance.com"
+   )
+
+   # Get Docker information
+   version = docker_client.get_version()
+   print(f"Docker version: {version}")
+
+   # List running containers
+   containers = docker_client.get_containers()
+   print(f"Running containers: {len(containers)}")
+
+   # List available images
+   images = docker_client.get_images()
+   print(f"Available images: {len(images)}")
+
+HTTP Client
+-----------
+
+Make authenticated HTTP requests::
+
+   from blackant.http.client import HTTPClient
+
+   # Create HTTP client with automatic authentication
+   http_client = HTTPClient(
+       base_url="https://your-api-endpoint.com",
+       auth=auth
+   )
+
+   # Make GET request
+   response = http_client.get("/api/data")
+   data = response.json()
+
+   # Make POST request
+   response = http_client.post("/api/create", json={"name": "example"})
+
+Service Management
+------------------
+
+Register and discover services::
+
+   from blackant.services.registry import ServiceRegistry
+
+   # Initialize service registry
+   registry = ServiceRegistry(auth=auth)
+
+   # Register a service
+   service_id = registry.register_service({
+       "name": "my-service",
+       "version": "1.0.0",
+       "health_check_url": "/health"
+   })
+
+   # Discover services
+   services = registry.discover_services("my-service")
+
+Configuration Management
+------------------------
+
+Load and manage configuration::
+
+   from blackant.config.manager import ConfigManager
+
+   # Initialize configuration
+   config = ConfigManager()
+   config.load_from_yaml("config.yaml")
+   config.load_from_environment()
+
+   # Access configuration values
+   database_url = config.get("database.url")
+   api_timeout = config.get("api.timeout", default=30)
+
+Architecture Overview
+=====================
+
+The BlackAnt SDK follows a modular architecture with clear separation of concerns:
+
+**Core Layer**
+   - Authentication and authorization (``blackant.auth``)
+   - Configuration management (``blackant.config``)
+   - Utilities and helpers (``blackant.utils``)
+
+**Integration Layer**
+   - Docker operations (``blackant.docker``)
+   - HTTP client (``blackant.http``)
+   - API client (``blackant.api``)
+
+**Service Layer**
+   - Service discovery and management (``blackant.services``)
+   - Design patterns and best practices (``blackant.patterns``)
+
+Error Handling
+==============
+
+The SDK provides comprehensive error handling with specific exception types::
+
+   from blackant.exceptions import BlackAntAuthenticationError, BlackAntDockerError
+
+   try:
+       auth.authenticate()
+   except BlackAntAuthenticationError as e:
+       print(f"Authentication failed: {e}")
+
+   try:
+       docker_client.get_containers()
+   except BlackAntDockerError as e:
+       print(f"Docker operation failed: {e}")
+
+Logging
+=======
+
+Enable comprehensive logging for debugging and monitoring::
+
+   from blackant.utils.logging import init_logging, get_logger
+
+   # Initialize logging with custom settings
+   init_logging(
+       app_name="MyApp",
+       log_level="DEBUG",
+       enable_colors=True,
+       enable_request_tracking=True
+   )
+
+   # Get logger for your module
+   logger = get_logger("my_module")
+   logger.info("Application started")
+
+Best Practices
+==============
+
+**Security**
+   - Always use environment variables for sensitive credentials
+   - Enable request ID tracking for audit trails
+   - Use the built-in sensitive data filtering in logs
+
+**Performance**
+   - Reuse HTTP client instances to benefit from connection pooling
+   - Configure appropriate timeout values for your environment
+   - Use caching for frequently accessed configuration values
+
+**Reliability**
+   - Implement proper error handling and retry logic
+   - Monitor service health and implement circuit breakers
+   - Use structured logging for better observability
+
+API Reference
+=============
+
+For detailed API documentation, see the module reference pages linked in the table of contents.
+Each module provides comprehensive documentation of classes, methods, and usage examples.
+
+Contributing
+============
+
+Contributions are welcome! Please see the project repository for contribution guidelines
+and development setup instructions.
+
+Support
+=======
+
+For support and questions:
+
+- Documentation: This site
+- Issues: GitHub Issues
+
+
+Indices and Tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

blackant_sdk-1.0.2/docs/source/modules/api.rst

@@ -0,0 +1,56 @@
+API Module
+==========
+
+The BlackAnt API module provides a comprehensive REST API client with automatic
+versioning, endpoint discovery, and response processing. It offers both high-level
+convenience methods and low-level API access for maximum flexibility.
+
+Features include:
+
+* Automatic API versioning and endpoint resolution
+* Type-safe request/response handling with validation
+* Comprehensive error handling and retry logic
+* Built-in authentication and authorization
+* Request/response interceptors and middleware support
+* Real-time API monitoring and performance metrics
+* OpenAPI specification integration and validation
+
+API Client
+----------
+
+High-level API client with automatic authentication and error handling.
+
+.. automodule:: blackant.api.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Endpoint Management
+-------------------
+
+Dynamic endpoint discovery and URL construction with versioning support.
+
+.. automodule:: blackant.api.endpoints
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+API Versioning
+--------------
+
+Automatic API version detection and compatibility management.
+
+.. automodule:: blackant.api.versioning
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+API Exceptions
+--------------
+
+Specialized exception handling for API-specific error conditions.
+
+.. automodule:: blackant.api.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance: