im-internals 0.4.2__tar.gz

im_internals-0.4.2/.github/workflows/publish.yaml

@@ -0,0 +1,39 @@
+name: Publish Python Package
+
+on:
+  push:
+    # any tag that starts with “v”, e.g. v0.2.0
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      # required for PyPI Trusted Publishing (OIDC) - no API token/secret needed or stored here.
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Create GitHub Release and upload wheel
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

im_internals-0.4.2/.gitignore

@@ -0,0 +1,72 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+eggs/
+*.egg-info/
+.eggs/
+
+# Virtual environment directories
+venv/
+.env/
+ENV/
+env/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+
+# IDE/editor directories and files
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Configuration files
+config.yaml
+
+# Logs and temporary files
+*.log
+/tmp/
+
+# SFTP key files
+id_rsa
+id_rsa.pub
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Sanity checks
+*.bak
+*.swp
+
+# SQLite databases
+*.sqlite3
+
+# JetBrains IDE
+*.iml
+out/

im_internals-0.4.2/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes. to **im-internals** will be documented in this file following the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
+
+## [Unreleased]
+- (Future enhancements and fixes)
+
+## [0.3.4] - 2026-09-10
+### Fixed
+- `transfer.Move.copy_files_or_folders`, `transfer.Move.copy_list_of_files_or_folders`, and
+  `transfer.recursive_folder_lookup` called the pre-rewrite two-argument `File(folder, filename)`
+  constructor and read a `.md_hash` attribute, both removed when `file.File` was rewritten to its
+  current single-argument `File(file_path)` / `.md5` API. Any of the three now raised
+  `TypeError: File.__init__() takes 2 positional arguments but 3 were given` as soon as a caller hit
+  the file-already-exists/hash-comparison branch (e.g. `Move.copy_files_or_folders(move_folder=True)`
+  recursing into an existing destination folder). No test coverage previously touched this path.
+
+## [0.3.0] - 2026-04-02
+### Added
+- `project_logging` module — centralised logging singleton with `progress`, `warn`,
+  `error`, `log_kv`, and `step` helpers, plus stdout formatting with timestamps.
+
+### Changed
+- All modules (`api`, `email`, `file`, `folder`, `ftp`, `sanitize`, `sftp`, `sql`,
+  `transfer`) migrated from bare `logging.*` / per-instance loggers to the
+  `project_logging` singleton.
+- `Ftp._log_setup()` and `Sftp._log_setup()` now delegate to `project_logging.get()`
+  instead of creating their own `FileHandler`; `logger_name` parameters kept for
+  backward compatibility.
+
+## [0.2.2] - 2025-08-14
+- Changed name of the package from "im-internals" -> "im_internals"
+
+
+## [0.2.1] - 2025-06-11
+### Added
+- Tests from `API` up to `SANITIZE`. Still needs tests for `SFTP, SQL, TRANSFER`
+- [publish.yaml](.github%2Fworkflows%2Fpublish.yaml) to build package with every update. Buils upon using `tag vX.X.X` system. Tag should contain the same version as [pyproject.toml](pyproject.toml).
+
+### Changed
+- Bumped project version to 0.2.1.
+- Added to [CONTRIBUTING.md](CONTRIBUTING.md) the `GIT commands` to verify if user has `Signed-off-by:` added to every commit 
+
+
+## [0.2.0] - 2025-06-08
+### Added
+- PDF processing and text extraction utilities via `pypdf`.
+
+### Changed
+- Bumped project version to 0.2.0.
+- Updated console script entry-point to PEP 621 format under `[project.entry-points]`.
+- Cleaned up setuptools-specific package configuration.
+
+## [0.1.0] - 2025-06-01
+### Added
+- Initial release of internal helper toolkit:
+  - Database helpers (`pyodbc`)
+  - SFTP & FTP utilities (`paramiko`, `ftplib`)
+  - API client wrappers with retry logic (`requests`, `tenacity`)
+  - Email send/receive utilities
+  - Configurable console script `cfg-commands`
+
+```markdown
+[Unreleased]: https://github.com/<company>/im-internals/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/<company>/im-internals/compare/v0.2.2...v0.3.0
+[0.2.2]: https://github.com/<company>/im-internals/compare/v0.2.1...v0.2.2
+[0.2.0]: https://github.com/<company>/im-internals/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/<company>/im-internals/releases/tag/v0.1.0
+```

im_internals-0.4.2/CONTRIBUTING.md

@@ -0,0 +1,129 @@
+# Writing CONTRIBUTING.md to disk for download
+content = """# Contributing to im-internals
+
+Thank you for considering contributing to **im-internals**, our internal helper toolkit. To keep the project consistent and maintainable, please follow these guidelines in your contributions.
+
+
+## Table of Contents
+1. [Code Style](#code-style)
+2. [Documentation](#documentation)
+3. [Assertions](#assertions)
+4. [Error Handling & Retries](#error-handling--retries)
+5. [Testing](#testing)
+6. [Commits & Pull Requests](#commits--pull-requests)
+7. [Dependencies & Compatibility](#dependencies--compatibility)
+
+---
+
+
+## Code Style
+
+- **Python Version**: Target Python 3.10+.
+- **Formatting**: Use [Black](https://github.com/psf/black) with default settings. Run `black .` before committing.
+- **Linting**: Follow [flake8](https://github.com/PyCQA/flake8) rules. Run `flake8 .` to catch common issues.
+- **Type Hints**: Annotate all functions and public methods with type hints. Use `typing` constructs where appropriate.
+- **Naming**: Use `snake_case` for functions and variables, `PascalCase` for classes, and `UPPER_CASE` for constants.
+
+
+## Documentation
+
+- **Docstrings**: Every public function, class, and module must include a docstring following the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
+- **README Updates**: If adding new features, update `README.md` to include usage examples and reference new functionality.
+- **CHANGELOG**: Maintain `CHANGELOG.md` entries for notable changes, fixes, and improvements.
+- **In-line Comments**: Add comments for non-obvious code sections to explain the intent and rationale.
+
+
+## Assertions
+
+- Use `assert` statements to enforce internal invariants and catch programmer errors early.
+- Avoid using `assert` for validating external inputs; instead, raise appropriate exceptions (e.g., `ValueError`, `TypeError`).
+
+
+## Error Handling & Retries
+
+- **Exceptions**: Catch and handle exceptions thoughtfully. Do not swallow broad exceptions.
+- **Retries**: For network or I/O operations (e.g., database queries, FTP/SFTP, API calls), use the [Tenacity](https://github.com/jd/tenacity) library:
+
+  ```python
+  from tenacity import retry, stop_after_attempt, wait_exponential
+
+  @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, max=10))
+  def fetch_data(...):
+      ...
+  ```
+  
+- **Configurable Parameters**: Allow retry parameters (attempts, wait time) to be configurable via function arguments or environment variables.
+
+
+## Testing
+
+- **Unit Tests**: Write unit tests using [pytest](https://pytest.org). Place tests in the `tests/` directory mirroring the package structure.  
+- **Test Coverage**: Aim for at least 80% coverage. Use `pytest --cov` to measure coverage.  
+- **Fixtures & Mocks**: Use `pytest` fixtures and `unittest.mock` for isolating external dependencies (e.g., network, file system).  
+- **CI Integration**: Ensure all tests pass locally and in the CI pipeline before submitting a PR.  
+
+
+
+## Commits & Pull Requests
+
+- **Branching**: Create feature branches named `feature/<name>` or bugfix branches named `bugfix/<issue-number>-<short-desc>`.  
+- **Commit Messages**: Use [Conventional Commits](https://www.conventionalcommits.org/) format:
+  ```text
+  feat: add SFTP upload helper
+  fix: handle timeout in API client
+  docs: update README with new CLI options
+  ```
+### **Signed-off-by**: 
+- At the end of each commit message, include a `Signed-off-by:` trailer with your name and email, for example:
+  ```text
+  Signed-off-by: Ivan Bilej <ivan.bilej@ironmountain.com>
+  ```
+  To add this automatically, use:
+  ```markdown
+  git commit -s -m "<type>: <scope> - <description>"
+  ```
+  To enable auto sign-off for commits in just this repository, run:
+  ```markdown
+  git config format.signoff true
+  ```
+  To enable auto sign-off for all your commits globally, run:
+  ```markdown
+  git config --global format.signoff true
+  ```
+
+### Verifying Signed-off-by
+- Run one of these GIT commands:
+  - Verifies local only for this repo
+    ```markdown
+    git config --get format.signoff
+    ```
+  - Verifies the global signoff
+    ```markdown
+    git config --get --global format.signoff
+    ```
+  If it prints `true`, you've enabled the signoff
+
+- OR Inspect the latest commit:
+  ```markdown
+  git log -1 --pretty=format:"%B" HEAD
+  ```
+  Ensure it ends with your `Signed-off-by:` trailer
+- Test with an empty commit:
+  ```markdown
+  git commit --allow-empty -s -m "test: verifying signoff"
+  git show -1
+  git reset --hard HEAD~1
+  ```
+  This lets you verify signoff without impacting your branch
+
+### **Pull Request**:
+  1. Reference the issue number in the PR title or description.  
+  2. Describe the change, motivation, and any relevant details.  
+  3. Ensure all checks (lint, tests, type checks) pass.  
+
+
+## Dependencies & Compatibility
+
+- **Pinning**: For library dependencies, specify minimum versions only. Colleagues may tighten in downstream projects.  
+- **Compatibility**: Ensure new code does not break existing functionality. Run the full test suite after updating dependencies.  
+

im_internals-0.4.2/LICENSE

@@ -0,0 +1,16 @@
+Effective as of June 8, 2025
+© 2025 Ivan Bilej
+
+Permission is hereby granted to Iron Mountain Czech Republic s.r.o. and Micro zone s.r.o.,
+and to individuals who are actively employed by either of these companies,
+to use, copy, modify, and distribute this software and derivative works
+within those companies only, for any purpose, royalty-free.
+
+External distribution, sublicensing, or publication of the source code
+or derivative works is prohibited without the copyright holder’s
+express written permission.
+
+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 COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY…

im_internals-0.4.2/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: im_internals
+Version: 0.4.2
+Summary: Internal helper toolkit for DB, (S)FTP, API, e-mail and other utilities.
+Author-email: Ivan Bilej <ivan.bilej@ironmountain.com>
+License: Effective as of June 8, 2025
+        © 2025 Ivan Bilej
+        
+        Permission is hereby granted to Iron Mountain Czech Republic s.r.o. and Micro zone s.r.o.,
+        and to individuals who are actively employed by either of these companies,
+        to use, copy, modify, and distribute this software and derivative works
+        within those companies only, for any purpose, royalty-free.
+        
+        External distribution, sublicensing, or publication of the source code
+        or derivative works is prohibited without the copyright holder’s
+        express written permission.
+        
+        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 COPYRIGHT HOLDER OR
+        CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY…
+        
+Project-URL: Source, https://github.com/Iron-Mountain-CR/IM_internals
+Project-URL: Tracker, https://github.com/Iron-Mountain-CR/IM_internals/issues
+Keywords: internal,helpers,toolkit,sftp,database,api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2
+Requires-Dist: paramiko>=3
+Requires-Dist: pyodbc>=5
+Requires-Dist: tenacity>=8
+Requires-Dist: pypdf>=1
+Dynamic: license-file
+
+# Writing README.md to disk for download
+readme_content = """# im-internals
+
+**im-internals** is an internal helper toolkit developed to streamline common tasks across database operations, (S)FTP transfers, API integrations, email handling, and other utilities within our organization.
+
+## Features
+
+- **Database Helpers**: Simplify connections and queries using `pyodbc`.
+- **SFTP & FTP Utilities**: Secure file transfers via `paramiko` and built-in `ftplib` wrappers.
+- **API Clients**: Lightweight wrappers for RESTful API interactions using `requests` and retry logic via `tenacity`.
+- **Email Utilities**: Send and receive emails with built-in MIME support.
+- **Configurable Commands**: Console script `cfg-commands` for running configuration-related tasks.
+- **PDF Processing**: Basic PDF manipulation and text extraction using `PyPDF2`.
+
+
+## Installation
+
+This package is **not published to PyPI** — `pip install im-internals` will not work. Install
+directly from a tagged GitHub Release wheel instead:
+
+```bash
+python -m pip install --upgrade "https://github.com/Iron-Mountain-CR/IM_internals/releases/download/<tag>/im_internals-<version>-py3-none-any.whl"
+```
+
+Replace `<tag>`/`<version>` with the release you want, e.g. for `v0.3.4`:
+
+```bash
+python -m pip install --upgrade "https://github.com/Iron-Mountain-CR/IM_internals/releases/download/v0.3.4/im_internals-0.3.4-py3-none-any.whl"
+```
+
+Verify the installed version:
+
+```bash
+python -c "import im_internals; print(im_internals.__version__)"
+```
+
+Alternatively, to always track the latest `main` (rebuilds from source on every install, no URL to
+update per release):
+
+```bash
+python -m pip install --upgrade "git+https://github.com/Iron-Mountain-CR/IM_internals.git@main"
+```
+
+
+## Quick Start
+### Database Example
+
+```python
+from im_internals.db import Database
+
+# Initialize and query
+db = Database(dsn="MY_DB_DSN")
+rows = db.query("SELECT * FROM my_table WHERE status=?", params=("active",))
+```
+
+
+### SFTP Upload
+
+```python
+from im_internals.sftp import SFTPClient
+
+client = SFTPClient(host="sftp.example.com", user="user", key_path="~/.ssh/id_rsa")
+client.upload_file(local_path="data.csv", remote_path="/incoming/data.csv")
+```
+
+
+### API Request with Retries
+```python
+from im_internals.api import ApiClient
+
+api = ApiClient(base_url="https://api.example.com", retry_config={"tries":3, "wait":2})
+response = api.get("/v1/resource")
+```
+
+
+### Send Email
+```python
+from im_internals.email import EmailClient
+
+email = EmailClient(smtp_host="smtp.example.com", port=587)
+email.send(
+    sender="noreply@company.com",
+    recipients=["user@company.com"],
+    subject="Test Email",
+    body="Hello from im-internals!"
+)
+```
+
+
+## CLI Usage
+```markdown
+# View available cfg-commands
+cfg-commands --help
+```
+
+
+## Configuration
+All configuration parameters—including database DSNs, SFTP credentials, API settings, and email credentials—are managed via company-standard .cfg files stored and secured externally. Do not include any credentials or config files in this repository. 
+A typical .cfg file follows the INI format. Example section for email:
+```markdown
+[email]
+host = smtp.example.com
+port = 587
+user = your_email_username
+password = your_email_password
+use_tls = true
+```
+By default, if you omit the -p/--path flag, cfg-commands will scan the current working directory for the first .cfg or .CFG file and use that. There is no built-in default path such as ~/.im-internals.cfg—to specify a file in another location, always use -p <path>.
+Clients will inject values into environment variables or client constructors based on the loaded .cfg file.
+
+
+
+## Contributing
+Thank you for considering contributing to **im-internals**! Please follow the guidelines outlined in [CONTRIBUTING.md](CONTRIBUTING.md) to keep the project consistent and maintainable.
+
+
+## License
+This toolkit is proprietary and intended for internal use only. See the [LICENSE](LICENSE) file at the project root for full terms.

im_internals-0.4.2/README.md

@@ -0,0 +1,118 @@
+# Writing README.md to disk for download
+readme_content = """# im-internals
+
+**im-internals** is an internal helper toolkit developed to streamline common tasks across database operations, (S)FTP transfers, API integrations, email handling, and other utilities within our organization.
+
+## Features
+
+- **Database Helpers**: Simplify connections and queries using `pyodbc`.
+- **SFTP & FTP Utilities**: Secure file transfers via `paramiko` and built-in `ftplib` wrappers.
+- **API Clients**: Lightweight wrappers for RESTful API interactions using `requests` and retry logic via `tenacity`.
+- **Email Utilities**: Send and receive emails with built-in MIME support.
+- **Configurable Commands**: Console script `cfg-commands` for running configuration-related tasks.
+- **PDF Processing**: Basic PDF manipulation and text extraction using `PyPDF2`.
+
+
+## Installation
+
+This package is **not published to PyPI** — `pip install im-internals` will not work. Install
+directly from a tagged GitHub Release wheel instead:
+
+```bash
+python -m pip install --upgrade "https://github.com/Iron-Mountain-CR/IM_internals/releases/download/<tag>/im_internals-<version>-py3-none-any.whl"
+```
+
+Replace `<tag>`/`<version>` with the release you want, e.g. for `v0.3.4`:
+
+```bash
+python -m pip install --upgrade "https://github.com/Iron-Mountain-CR/IM_internals/releases/download/v0.3.4/im_internals-0.3.4-py3-none-any.whl"
+```
+
+Verify the installed version:
+
+```bash
+python -c "import im_internals; print(im_internals.__version__)"
+```
+
+Alternatively, to always track the latest `main` (rebuilds from source on every install, no URL to
+update per release):
+
+```bash
+python -m pip install --upgrade "git+https://github.com/Iron-Mountain-CR/IM_internals.git@main"
+```
+
+
+## Quick Start
+### Database Example
+
+```python
+from im_internals.db import Database
+
+# Initialize and query
+db = Database(dsn="MY_DB_DSN")
+rows = db.query("SELECT * FROM my_table WHERE status=?", params=("active",))
+```
+
+
+### SFTP Upload
+
+```python
+from im_internals.sftp import SFTPClient
+
+client = SFTPClient(host="sftp.example.com", user="user", key_path="~/.ssh/id_rsa")
+client.upload_file(local_path="data.csv", remote_path="/incoming/data.csv")
+```
+
+
+### API Request with Retries
+```python
+from im_internals.api import ApiClient
+
+api = ApiClient(base_url="https://api.example.com", retry_config={"tries":3, "wait":2})
+response = api.get("/v1/resource")
+```
+
+
+### Send Email
+```python
+from im_internals.email import EmailClient
+
+email = EmailClient(smtp_host="smtp.example.com", port=587)
+email.send(
+    sender="noreply@company.com",
+    recipients=["user@company.com"],
+    subject="Test Email",
+    body="Hello from im-internals!"
+)
+```
+
+
+## CLI Usage
+```markdown
+# View available cfg-commands
+cfg-commands --help
+```
+
+
+## Configuration
+All configuration parameters—including database DSNs, SFTP credentials, API settings, and email credentials—are managed via company-standard .cfg files stored and secured externally. Do not include any credentials or config files in this repository. 
+A typical .cfg file follows the INI format. Example section for email:
+```markdown
+[email]
+host = smtp.example.com
+port = 587
+user = your_email_username
+password = your_email_password
+use_tls = true
+```
+By default, if you omit the -p/--path flag, cfg-commands will scan the current working directory for the first .cfg or .CFG file and use that. There is no built-in default path such as ~/.im-internals.cfg—to specify a file in another location, always use -p <path>.
+Clients will inject values into environment variables or client constructors based on the loaded .cfg file.
+
+
+
+## Contributing
+Thank you for considering contributing to **im-internals**! Please follow the guidelines outlined in [CONTRIBUTING.md](CONTRIBUTING.md) to keep the project consistent and maintainable.
+
+
+## License
+This toolkit is proprietary and intended for internal use only. See the [LICENSE](LICENSE) file at the project root for full terms.

im_internals-0.4.2/docs/api/api.md

@@ -0,0 +1,4 @@
+<!-- docs/api/api.md -->
+# api.py
+
+::: IM_internals.api

im_internals-0.4.2/docs/api/cfg_commands.md

@@ -0,0 +1,4 @@
+<!-- docs/api/cfg_commands.md -->
+# cfg_commands.py
+
+::: IM_internals.cfg_commands

im_internals-0.4.2/docs/api/email.md

@@ -0,0 +1,4 @@
+<!-- docs/api/email.md -->
+# email.py
+
+::: IM_internals.email

im_internals-0.4.2/docs/api/file.md

@@ -0,0 +1,4 @@
+<!-- docs/api/file.md -->
+# file.py
+
+::: IM_internals.file

im_internals-0.4.2/docs/api/folder.md

@@ -0,0 +1,4 @@
+<!-- docs/api/folder.md -->
+# folder.py
+
+::: IM_internals.folder

im_internals-0.4.2/docs/api/ftp.md

@@ -0,0 +1,4 @@
+<!-- docs/api/ftp.md -->
+# ftp.py
+
+::: IM_internals.ftp

im_internals-0.4.2/docs/api/sanitize.md

@@ -0,0 +1,4 @@
+<!-- docs/api/sanitize.md -->
+# sanitize.py
+
+::: IM_internals.sanitize

im_internals-0.4.2/docs/api/sftp.md

@@ -0,0 +1,4 @@
+<!-- docs/api/sftp.md -->
+# sftp.py
+
+::: IM_internals.sftp

im_internals-0.4.2/docs/api/sql.md

@@ -0,0 +1,4 @@
+<!-- docs/api/sql.md -->
+# sql.py
+
+::: IM_internals.sql

im_internals-0.4.2/docs/api/transfer.md

@@ -0,0 +1,4 @@
+<!-- docs/api/transfer.md -->
+# transfer.py
+
+::: IM_internals.transfer