tsmetallic 1.0.0__tar.gz

tsmetallic-1.0.0/.vscode/PythonImportHelper-v2-Completion.json

@@ -0,0 +1,330 @@
+[
+    {
+        "label": "Subnet",
+        "importPath": "ipamanager.subnet",
+        "description": "ipamanager.subnet",
+        "isExtraImport": true,
+        "detail": "ipamanager.subnet",
+        "documentation": {}
+    },
+    {
+        "label": "get_term_size",
+        "importPath": "ipamanager.utils",
+        "description": "ipamanager.utils",
+        "isExtraImport": true,
+        "detail": "ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "err_and_exit",
+        "importPath": "ipamanager.utils",
+        "description": "ipamanager.utils",
+        "isExtraImport": true,
+        "detail": "ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "show_help",
+        "importPath": "ipamanager.utils",
+        "description": "ipamanager.utils",
+        "isExtraImport": true,
+        "detail": "ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "err_and_exit",
+        "importPath": "ipamanager.utils",
+        "description": "ipamanager.utils",
+        "isExtraImport": true,
+        "detail": "ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "sys",
+        "kind": 6,
+        "isExtraImport": true,
+        "importPath": "sys",
+        "description": "sys",
+        "detail": "sys",
+        "documentation": {}
+    },
+    {
+        "label": "json",
+        "kind": 6,
+        "isExtraImport": true,
+        "importPath": "json",
+        "description": "json",
+        "detail": "json",
+        "documentation": {}
+    },
+    {
+        "label": "Console",
+        "importPath": "rich.console",
+        "description": "rich.console",
+        "isExtraImport": true,
+        "detail": "rich.console",
+        "documentation": {}
+    },
+    {
+        "label": "Console",
+        "importPath": "rich.console",
+        "description": "rich.console",
+        "isExtraImport": true,
+        "detail": "rich.console",
+        "documentation": {}
+    },
+    {
+        "label": "settings",
+        "importPath": "ipamanager.config",
+        "description": "ipamanager.config",
+        "isExtraImport": true,
+        "detail": "ipamanager.config",
+        "documentation": {}
+    },
+    {
+        "label": "IpamDb",
+        "importPath": "ipamanager.db",
+        "description": "ipamanager.db",
+        "isExtraImport": true,
+        "detail": "ipamanager.db",
+        "documentation": {}
+    },
+    {
+        "label": "Report",
+        "importPath": "ipamanager.reports",
+        "description": "ipamanager.reports",
+        "isExtraImport": true,
+        "detail": "ipamanager.reports",
+        "documentation": {}
+    },
+    {
+        "label": "ReportRecord",
+        "importPath": "ipamanager.reports",
+        "description": "ipamanager.reports",
+        "isExtraImport": true,
+        "detail": "ipamanager.reports",
+        "documentation": {}
+    },
+    {
+        "label": "os",
+        "kind": 6,
+        "isExtraImport": true,
+        "importPath": "os",
+        "description": "os",
+        "detail": "os",
+        "documentation": {}
+    },
+    {
+        "label": "Path",
+        "importPath": "pathlib",
+        "description": "pathlib",
+        "isExtraImport": true,
+        "detail": "pathlib",
+        "documentation": {}
+    },
+    {
+        "label": "sqlite3",
+        "kind": 6,
+        "isExtraImport": true,
+        "importPath": "sqlite3",
+        "description": "sqlite3",
+        "detail": "sqlite3",
+        "documentation": {}
+    },
+    {
+        "label": "time",
+        "kind": 6,
+        "isExtraImport": true,
+        "importPath": "time",
+        "description": "time",
+        "detail": "time",
+        "documentation": {}
+    },
+    {
+        "label": "Table",
+        "importPath": "rich.table",
+        "description": "rich.table",
+        "isExtraImport": true,
+        "detail": "rich.table",
+        "documentation": {}
+    },
+    {
+        "label": "Panel",
+        "importPath": "rich.panel",
+        "description": "rich.panel",
+        "isExtraImport": true,
+        "detail": "rich.panel",
+        "documentation": {}
+    },
+    {
+        "label": "tsm.semantic_colors",
+        "kind": 6,
+        "isExtraImport": true,
+        "importPath": "tsm.semantic_colors",
+        "description": "tsm.semantic_colors",
+        "detail": "tsm.semantic_colors",
+        "documentation": {}
+    },
+    {
+        "label": "AddressPool",
+        "kind": 6,
+        "importPath": "src.tsm.ipamanager.address_pool",
+        "description": "src.tsm.ipamanager.address_pool",
+        "peekOfCode": "class AddressPool:\n    \"\"\"A contiguous range of IP addresses intended to provide logical\n    boundaries for automated allocation and reporting.\n    \"\"\"\n    def list_records(self):\n        \"\"\"List detail records of members of the pool.\n        Returns:\n            list: A list of tuples, each a detail record of a member of the\n            pool.\n        \"\"\"",
+        "detail": "src.tsm.ipamanager.address_pool",
+        "documentation": {}
+    },
+    {
+        "label": "cli_parser",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.cli",
+        "description": "src.tsm.ipamanager.cli",
+        "peekOfCode": "def cli_parser(args=sys.argv):\n    \"\"\"Handles unpacking of sys.argv.\n    Args:\n        args (list): List of arguments received by the module at runtime.\n        Defaults to sys.argv.\n    Returns:\n        tuple: a subcommand, which selects the function to be called by the\n        CLI, and a list of parameters to be made available to that function.\n    \"\"\"\n    if len(args) == 0:",
+        "detail": "src.tsm.ipamanager.cli",
+        "documentation": {}
+    },
+    {
+        "label": "cli",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.cli",
+        "description": "src.tsm.ipamanager.cli",
+        "peekOfCode": "def cli():\n    \"\"\"Calls functions based on the arguments used to run the application.\"\"\"\n    subcmd, params = cli_parser()\n    dbpath = config[\"database\"][\"path\"]\n    dbfields = config[\"database\"][\"fields\"]\n    db = IpamDb(str(dbpath))\n    match subcmd:\n        case \"available\":\n            print(db.is_unassigned(params[0]))\n        case \"setup\":",
+        "detail": "src.tsm.ipamanager.cli",
+        "documentation": {}
+    },
+    {
+        "label": "dump_config",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.config",
+        "description": "src.tsm.ipamanager.config",
+        "peekOfCode": "def dump_config():\n    print(json.dumps(settings))",
+        "detail": "src.tsm.ipamanager.config",
+        "documentation": {}
+    },
+    {
+        "label": "config_file",
+        "kind": 5,
+        "importPath": "src.tsm.ipamanager.config",
+        "description": "src.tsm.ipamanager.config",
+        "peekOfCode": "config_file = Path(os.environ.get(\"XDG_CONFIG_HOME\")) / \"ipam/settings.conf\"\nif not config_file.exists():\n    err_and_exit(f\"Missing Config - {config_file}\")\nwith open(config_file, \"r\", encoding=\"utf-8\") as f:\n    settings = json.load(f)\ndef dump_config():\n    print(json.dumps(settings))",
+        "detail": "src.tsm.ipamanager.config",
+        "documentation": {}
+    },
+    {
+        "label": "Database",
+        "kind": 6,
+        "importPath": "src.tsm.ipamanager.db",
+        "description": "src.tsm.ipamanager.db",
+        "peekOfCode": "class Database:\n    \"\"\"Handles database operations for SQLite3.\n    Provides methods for connecting to the database, executing SQL queries,\n    and fetching results. This class is intended to be used as a base class\n    for specific database functionality.\n    Attributes:\n        db_name (str): The name of the SQLite3 database file.\n        conn (sqlite3.Connection): The database connection object.\n    \"\"\"\n    def __init__(self, db_name):",
+        "detail": "src.tsm.ipamanager.db",
+        "documentation": {}
+    },
+    {
+        "label": "IpamDb",
+        "kind": 6,
+        "importPath": "src.tsm.ipamanager.db",
+        "description": "src.tsm.ipamanager.db",
+        "peekOfCode": "class IpamDb(Database):\n    \"\"\"Specialized database class for managing IP address data.\n    This class extends the Database class and provides additional functionality\n    for managing IP address records, such as assigning, unassigning, and\n    retrieving IP addresses.\n    Attributes:\n        main_table (dict): A dictionary containing the structure of the IP\n        address table.\n    \"\"\"\n    def __init__(self, db_name):",
+        "detail": "src.tsm.ipamanager.db",
+        "documentation": {}
+    },
+    {
+        "label": "ReportRecord",
+        "kind": 6,
+        "importPath": "src.tsm.ipamanager.reports",
+        "description": "src.tsm.ipamanager.reports",
+        "peekOfCode": "class ReportRecord:\n    def __init__(self, addr_id, address, host, pool):\n        hstyle_dimmed = \"grey23\"\n        hstyle_bright = \"sky_blue3\"\n        pstyle = {\n            \"none\": \"color(238)\",\n            \"oleander\": \"color(88)\",\n            \"dahlia\": \"color(91)\",\n            \"hemlock\": \"color(98)\",\n            \"dhcp\": \"color(141)\"",
+        "detail": "src.tsm.ipamanager.reports",
+        "documentation": {}
+    },
+    {
+        "label": "Report",
+        "kind": 6,
+        "importPath": "src.tsm.ipamanager.reports",
+        "description": "src.tsm.ipamanager.reports",
+        "peekOfCode": "class Report:\n    def __init__(self, name, fields, records):\n        self.console = Console()\n        self.name = name\n        self.fields = fields\n        self.records = records\n    def display_table(self):\n        table = Table(title=self.name,\n                      padding=(0, 4),\n                      expand=False,",
+        "detail": "src.tsm.ipamanager.reports",
+        "documentation": {}
+    },
+    {
+        "label": "read_file",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.utils",
+        "description": "src.tsm.ipamanager.utils",
+        "peekOfCode": "def read_file(filepath):\n    \"\"\"Reads and returns the content of a file.\"\"\"\n    try:\n        with open(filepath, 'r') as file:\n            return file.read()\n    except FileNotFoundError:\n        return None\ndef write_file(filepath, content):\n    \"\"\"Writes content to a file.\"\"\"\n    try:",
+        "detail": "src.tsm.ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "write_file",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.utils",
+        "description": "src.tsm.ipamanager.utils",
+        "peekOfCode": "def write_file(filepath, content):\n    \"\"\"Writes content to a file.\"\"\"\n    try:\n        with open(filepath, 'w') as file:\n            file.write(content)\n        return True\n    except Exception as e:\n        print(f\"Error writing to file: {e}\")\n        return False\ndef create_directory(dirpath):",
+        "detail": "src.tsm.ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "create_directory",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.utils",
+        "description": "src.tsm.ipamanager.utils",
+        "peekOfCode": "def create_directory(dirpath):\n    \"\"\"Creates a directory if it doesn't exist.\"\"\"\n    if not os.path.exists(dirpath):\n        os.makedirs(dirpath)\n        return True\n    return False\ndef load_json(filepath):\n    \"\"\"Loads JSON data from a file.\"\"\"\n    try:\n        with open(filepath, 'r') as file:",
+        "detail": "src.tsm.ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "load_json",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.utils",
+        "description": "src.tsm.ipamanager.utils",
+        "peekOfCode": "def load_json(filepath):\n    \"\"\"Loads JSON data from a file.\"\"\"\n    try:\n        with open(filepath, 'r') as file:\n            return json.load(file)\n    except (FileNotFoundError, json.JSONDecodeError):\n        return None\ndef save_json(filepath, data, indent=4):\n    \"\"\"Saves data to a JSON file.\"\"\"\n    try:",
+        "detail": "src.tsm.ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "save_json",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.utils",
+        "description": "src.tsm.ipamanager.utils",
+        "peekOfCode": "def save_json(filepath, data, indent=4):\n    \"\"\"Saves data to a JSON file.\"\"\"\n    try:\n        with open(filepath, 'w') as file:\n            json.dump(data, file, indent=indent)\n        return True\n    except Exception as e:\n        print(f\"Error saving JSON to file: {e}\")\n        return False\ndef get_term_size():",
+        "detail": "src.tsm.ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "get_term_size",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.utils",
+        "description": "src.tsm.ipamanager.utils",
+        "peekOfCode": "def get_term_size():\n    \"\"\"Return terminal dimensions (width, height)\"\"\"\n    try:\n        terminal_size = os.get_terminal_size()\n        width = terminal_size.columns\n        height = terminal_size.lines\n        return width, height\n    except Exception as e:\n        print(f\"Error getting response from terminal: {e}\")\n        return False",
+        "detail": "src.tsm.ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "err_and_exit",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.utils",
+        "description": "src.tsm.ipamanager.utils",
+        "peekOfCode": "def err_and_exit(message):\n    \"\"\"Print error message and exit.\n    Args:\n        message (string): Info to be displayed before exiting.  Usually\n        describes the error or reason for the exit.\n    \"\"\"\n    sys.exit(print(f\"\\001\\033[31m\\002Error:\\001\\033[m\\002 {message}\"))\ndef show_help():\n    \"\"\"Display a help message with a list of CLI subcommands.\"\"\"\n    print(\"\\nUsage: ipm SUBCOMMAND [ARG[S]]\\n\")",
+        "detail": "src.tsm.ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "show_help",
+        "kind": 2,
+        "importPath": "src.tsm.ipamanager.utils",
+        "description": "src.tsm.ipamanager.utils",
+        "peekOfCode": "def show_help():\n    \"\"\"Display a help message with a list of CLI subcommands.\"\"\"\n    print(\"\\nUsage: ipm SUBCOMMAND [ARG[S]]\\n\")\n    print(\"Subcommand:\")\n    print(\"      setup  -   Initialize database (no assignments)\")\n    print(\"      assign -   Assign ADDRESS to HOST\")\n    print(\"      next   -   Assign next available IP in POOL to HOST\")\n    print(\"      show   -   Print details (host, pool) for ADDRESS\")\n    print(\"      list   -   Show all IPs, host assignments and pools\")\n    print(\"      help   -   Display this message\")",
+        "detail": "src.tsm.ipamanager.utils",
+        "documentation": {}
+    },
+    {
+        "label": "scolor",
+        "kind": 5,
+        "importPath": "app",
+        "description": "app",
+        "peekOfCode": "scolor = sc.SemanticColor(\"external\")\nprint(scolor)",
+        "detail": "app",
+        "documentation": {}
+    }
+]

tsmetallic-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 tsharley
+
+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.

tsmetallic-1.0.0/Makefile

@@ -0,0 +1,98 @@
+.DELETE_ON_ERROR:
+.ONESHELL:
+.SHELLFLAGS   := -eu -o pipefail -c
+MAKEFLAGS     += --warn-undefined-variables
+MAKEFLAGS     += --no-builtin-rules
+SHELL         := bash
+
+.PHONY: help tree init run view clean debug build install config
+
+.DEFAULT_GOAL := help
+
+VENV           = .venv
+ACTIVATE       = $(VENV)/bin/activate
+PIP            = $(VENV)/bin/pip
+PYTHON         = $(VENV)/bin/python
+BREWPYTHON     = /opt/homebrew/bin/python3
+PYGITIGNORE    = $(HOME)/Repos/gitignore/Python.gitignore
+GIT_ORG        = ts
+GIT_REPO       = $$(basename $$(pwd))
+GIT_URL        = http://git.tsmetallic.com/$(GIT_ORG)/$(GIT_REPO)
+PACKAGE        = tsm
+PROJECT        = tsm
+
+
+help:
+	@echo -e ""
+	@echo -e "  Help - Available Make Commands"
+	@echo -e " ====================================================================="
+	@echo -e ""
+	@echo -e "  Setup Commands:"
+	@echo -e ""
+	@echo -e "      make init     :  Initialize version control and link remote"
+	@echo -e "      make install  :  Install pkg/module in local environment"
+	@echo -e ""
+	@echo -e "  Dev Commands:"
+	@echo -e ""
+	@echo -e "      make tree     :  Show project's file system excluding caches"
+	@echo -e "      make view     :  Display a snapshot of each database table"
+	@echo -e "      make config   :  Display runtime configuration"
+	@echo -e "      make debug    :  Toggle the configuration option for debug mode"
+	@echo -e ""
+	@echo -e "  Test Commands:"
+	@echo -e ""
+	@echo -e "      make test     :  Execute full test suite"
+	@echo -e "      make utest    :  Execute unit tests"
+	@echo -e "      make itest    :  Execute integration tests"
+	@echo -e ""
+	@echo -e "  Build Commands:"
+	@echo -e ""
+	@echo -e "      make build    :  Compile project to wheel distribution"
+	@echo -e "      make clean    :  Remove cache files and build artifacts"
+	@echo -e ""
+
+tree:
+	@tree -I "*.egg-info|__pycache__"
+
+config: config.json
+	@cat config.json | jq
+
+debug:
+	@/Users/tjsharley/Projects/tsm/.venv/bin/tsm-tgl
+
+view:
+	@source $(ACTIVATE) && $(PYTHON) src/heroes/view.py database.db team
+	@source $(ACTIVATE) && $(PYTHON) src/heroes/view.py database.db hero
+
+build: $(ACTIVATE)
+	@source $(ACTIVATE) && $(PYTHON) -m build
+
+install: $(ACTIVATE)
+	@source $(ACTIVATE) && $(PYTHON) -m pip install -e .
+
+run: $(ACTIVATE) $(EPSCRIPT)
+	@source $(ACTIVATE) && $(EPSCRIPT)
+
+$(ACTIVATE): requirements.txt
+	@$(BREWPYTHON) -m venv $(VENV)
+	@$(PYTHON) -m pip install --upgrade pip
+	@$(PIP) install -r requirements.txt
+
+clean:
+	@rm -rf src/$(PKGNAME)/__pycache__
+	@rm -rf proc/out/*
+
+requirements.txt:
+	@pip freeze --exclude-editable >> 'requirements.txt'
+
+init: .git
+
+.git: .gitignore
+	@git init .
+	@git add .
+	@git commit -a -m 'Initial commit'
+	@git remote add origin $(GIT_URL)
+	@git push -u origin main
+
+.gitignore:
+	@cp $(PYGITIGNORE) .gitignore

tsmetallic-1.0.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: tsmetallic
+Version: 1.0.0
+Summary: A collection of reusable Python utilities and personal libraries.
+Author-email: tsmetallic <ts-metallic@proton.me>
+Description-Content-Type: text/markdown
+License-Expression: MIT
+License-File: LICENSE
+
+# tsmetallic
+> A lightweight collection of reusable Python utilities for building robust applications.
+`tsmetallic` is a modular utility library that provides the infrastructure code commonly needed across Python projects. It brings together reusable components for logging, configuration management, data loading, registries, dispatchers, and other application building blocks into a single, consistent package.
+Rather than being a framework, `tsmetallic` is designed to complement your existing architecture by providing small, focused utilities that solve common problems with minimal dependencies.
+
+## Installation
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install tsmetallic
+```
+
+## Why tsmetallic?
+Most Python applications eventually grow a collection of shared infrastructure:
+* Logging configuration
+* Configuration loading
+* File and data loaders
+* Registry and dispatcher patterns
+* General-purpose helper utilities
+Instead of rewriting these components for every project, `tsm` packages them into reusable modules with a consistent API.
+
+## Features
+* **Modular** — Import only the functionality you need.
+* **Lightweight** — Designed to stay out of your way.
+* **Reusable** — Components intended for use across many projects.
+* **Practical** — Focused on solving common application problems.
+* **Well-typed** — Modern Python with type annotations where appropriate.
+
+## Included Modules
+Although the library continues to evolve, it currently includes utilities such as:
+
+| Module                | Purpose                              |
+| --------------------- | ------------------------------------ |
+| `tsmetallic.logging`  | Logging configuration and helpers    |
+| `tsmetallic.config`   | Configuration loading and management |
+| `tsmetallic.loaders`  | Common data and file loaders         |
+| `tsmetallic.registry` | Generic registry implementations     |
+| `tsmetallic.utils`    | General-purpose utility functions    |
+
+Additional modules are added as reusable functionality emerges from real-world projects.
+
+## Example
+```python
+import tsmetallic.logging
+
+logger = tsmetallic.logging.setup_logging()
+logger.info('Logging initialized')
+```
+Because each module is independent, you can adopt only the pieces that fit your application.
+
+## Design Principles
+`tsmetallic` is built around a few simple ideas:
+* Prefer composition over frameworks.
+* Keep abstractions small and focused.
+* Minimize dependencies.
+* Write code that is easy to understand and reuse.
+* Favor explicit behavior over hidden magic.
+
+## Compatibility
+* Python >= 3.12
+* macOS
+* Linux
+* Windows?
+
+## Documentation
+Each module includes docstrings and examples. As the package grows, additional documentation and API references will be added.
+
+## Contributing
+Issues, bug reports, and suggestions are welcome. While `tsm` primarily serves as a personal utility library, improvements that make the package more generally useful are appreciated.
+
+## License
+Released under the terms of the project's license. See `LICENSE` for details.
+

tsmetallic-1.0.0/README.md

@@ -0,0 +1,72 @@
+# tsmetallic
+> A lightweight collection of reusable Python utilities for building robust applications.
+`tsmetallic` is a modular utility library that provides the infrastructure code commonly needed across Python projects. It brings together reusable components for logging, configuration management, data loading, registries, dispatchers, and other application building blocks into a single, consistent package.
+Rather than being a framework, `tsmetallic` is designed to complement your existing architecture by providing small, focused utilities that solve common problems with minimal dependencies.
+
+## Installation
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install tsmetallic
+```
+
+## Why tsmetallic?
+Most Python applications eventually grow a collection of shared infrastructure:
+* Logging configuration
+* Configuration loading
+* File and data loaders
+* Registry and dispatcher patterns
+* General-purpose helper utilities
+Instead of rewriting these components for every project, `tsm` packages them into reusable modules with a consistent API.
+
+## Features
+* **Modular** — Import only the functionality you need.
+* **Lightweight** — Designed to stay out of your way.
+* **Reusable** — Components intended for use across many projects.
+* **Practical** — Focused on solving common application problems.
+* **Well-typed** — Modern Python with type annotations where appropriate.
+
+## Included Modules
+Although the library continues to evolve, it currently includes utilities such as:
+
+| Module                | Purpose                              |
+| --------------------- | ------------------------------------ |
+| `tsmetallic.logging`  | Logging configuration and helpers    |
+| `tsmetallic.config`   | Configuration loading and management |
+| `tsmetallic.loaders`  | Common data and file loaders         |
+| `tsmetallic.registry` | Generic registry implementations     |
+| `tsmetallic.utils`    | General-purpose utility functions    |
+
+Additional modules are added as reusable functionality emerges from real-world projects.
+
+## Example
+```python
+import tsmetallic.logging
+
+logger = tsmetallic.logging.setup_logging()
+logger.info('Logging initialized')
+```
+Because each module is independent, you can adopt only the pieces that fit your application.
+
+## Design Principles
+`tsmetallic` is built around a few simple ideas:
+* Prefer composition over frameworks.
+* Keep abstractions small and focused.
+* Minimize dependencies.
+* Write code that is easy to understand and reuse.
+* Favor explicit behavior over hidden magic.
+
+## Compatibility
+* Python >= 3.12
+* macOS
+* Linux
+* Windows?
+
+## Documentation
+Each module includes docstrings and examples. As the package grows, additional documentation and API references will be added.
+
+## Contributing
+Issues, bug reports, and suggestions are welcome. While `tsm` primarily serves as a personal utility library, improvements that make the package more generally useful are appreciated.
+
+## License
+Released under the terms of the project's license. See `LICENSE` for details.

tsmetallic-1.0.0/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["flit_core >=3.11,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "tsmetallic"
+authors = [{name = "tsmetallic", email = "ts-metallic@proton.me"}]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+dynamic = ["version", "description"]
+
+# [tool.flit.packages.find]
+#     where = ["src"]

tsmetallic-1.0.0/requirements.txt

@@ -0,0 +1,20 @@
+attrs==26.1.0
+build==1.3.0
+cyclopts==4.21.1
+docstring_parser==0.18.0
+iniconfig==2.3.0
+markdown-it-py==4.0.0
+mdurl==0.1.2
+packaging==25.0
+pluggy==1.6.0
+prompt_toolkit==3.0.52
+Pygments==2.19.2
+pyproject_hooks==1.2.0
+pytest==9.1.1
+python-json-logger==4.1.0
+PyYAML==6.0.3
+questionary==2.1.1
+rich==14.1.0
+rich-rst==2.1.0
+setuptools==80.9.0
+wcwidth==0.2.14

tsmetallic-1.0.0/tests/test_tsm_config.py

@@ -0,0 +1,8 @@
+import tsm.config
+import tsm.loader
+
+
+def test_config_reads_file():
+    loader = tsm.loader.DataLoader.get_loader("json")
+    config = loader.load(loader, 'settings.json')
+    assert config["logging"]["console"] == True

tsmetallic-1.0.0/tests/test_tsm_logging.py

@@ -0,0 +1,5 @@
+# import tsm.logging
+
+# def test_logger_writes_to_console():
+#     logger = tsm.logging.setup_logging()
+#     assert logger.info('test').endswith('test')

tsmetallic-1.0.0/tsmetallic/__init__.py

@@ -0,0 +1,2 @@
+"""A collection of reusable Python utilities and personal libraries."""
+__version__ = '1.0.0'

tsmetallic-1.0.0/tsmetallic/config/__init__.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+from typing import Any
+import tsm.loader
+
+
+class Config:
+
+    paths = ['.', './config']
+    names = ['config', 'settings']
+    extensions = ['json', 'toml', 'yaml', 'yml']
+
+    def __init__(self, path: Path | None = None) -> None:
+        if path is not None and Path(path).exists():
+            self.path = Path(path)
+        else:
+            for path in self.paths:
+                for name in self.names:
+                    for extension in self.extensions:
+                        if not (Path(path) / f'{name}.{extension}').exists():
+                            continue
+                        else:
+                            self.path = Path(path) / f'{name}.{extension}'
+
+    def load(self) -> dict[str, Any]:
+        print(f'loader_path: {self.path}')
+        filetype = self.path.suffix.replace('.', '')
+        loader = tsm.loader.DataLoader.get_loader(filetype)
+        print(f'loader.load({self.path})')
+        loader.load(self.path)

tsmetallic-1.0.0/tsmetallic/loader/__init__.py

@@ -0,0 +1,52 @@
+class DataLoader:
+    _registry = {}
+
+    def __init_subclass__(cls, fmt=None, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if fmt:
+            DataLoader._registry[fmt] = cls
+
+    @classmethod
+    def get_loader(cls, fmt):
+        if fmt not in cls._registry:
+            raise ValueError(f"No loader for {fmt!r}. "
+                             f"Available: {list(cls._registry)}")
+        return cls._registry[fmt]
+
+
+class CSVLoader(DataLoader, fmt="csv"):
+
+    def load(self, path):
+        import csv
+        return f"Loading CSV from {path}"
+
+
+class JSONLoader(DataLoader, fmt="json"):
+
+    def load(self, path):
+        import json
+        with open(path, 'r', encoding='utf-8') as file:
+            data = json.load(file)
+        return data
+
+
+class YAMLLoader(DataLoader, fmt="yaml"):
+
+    def load(self, path):
+        import yaml
+        with open(path, 'rb') as file:
+            data = yaml.safe_load(file)
+        return data
+
+
+class TOMLLoader(DataLoader, fmt="toml"):
+
+    def load(self, path):
+        import tomllib
+        with open(path, 'rb') as file:
+            data = tomllib.load(file)
+        return data
+
+
+# loader = DataLoader.get_loader("parquet")
+# print(loader.load("sales.parquet"))

tsmetallic-1.0.0/tsmetallic/logging/__init__.py

@@ -0,0 +1,75 @@
+import logging
+import logging.handlers
+from enum import Enum
+
+
+class LogLevel(Enum):
+    NOTSET = 0
+    DEBUG = 10
+    INFO = 20
+    WARN = 30
+    ERROR = 40
+    CRITICAL = 50
+
+
+def setup_logging(
+    *,
+    name: str = __name__,
+    console: bool = True,
+    path: str | None = None,
+    level: LogLevel = 20,
+):
+    """Provides a logger with optional FileHandler and StreamHandler.
+
+    Parameters
+    ----------
+    name: str
+        The new logger's name (default: __name__)
+    console: bool
+        Whether or not to activate the console stream logger
+    path: str | None = None
+        Path to a file for persistent logging if needed
+    level: LogLevel
+        The minimum level threshold for messages to appear in your logs
+
+    Returns
+    -------
+    Logger
+        A configured logging.Logger instance
+    """
+
+    handlers = []
+
+    # Initialize a logger
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # 1. Formatter (applied to all handlers)
+    fmt = "%(asctime)s [%(levelname)s "
+    fmt += "%(name)s(line:%(lineno)d)]: %(message)s"
+    formatter = logging.Formatter(fmt=fmt, datefmt="%Y%m%d.%H:%M:%S")
+
+    # 2. File Handler (for persistent storage)
+    if path is not None:
+        file_handler = logging.handlers.RotatingFileHandler(
+            path,
+            maxBytes=1024 * 1024,
+            backupCount=5,
+        )
+        file_handler.setLevel(level)
+        file_handler.setFormatter(formatter)
+        handlers.append(file_handler)
+
+    # 3. Console Handler (for real-time feedback)
+    if console:
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(level)
+        console_handler.setFormatter(formatter)
+        handlers.append(console_handler)
+
+    # 4. Add handlers (if they are not already present)
+    if not logger.handlers:
+        for handler in handlers:
+            logger.addHandler(handler)
+
+    return logger

tsmetallic-1.0.0/tsmetallic/register/__init__.py

@@ -0,0 +1 @@
+