ruf-common 1.0.1__tar.gz

ruf_common-1.0.1/LICENSE

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

ruf_common-1.0.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: ruf-common
+Version: 1.0.1
+Summary: Common Python utilities
+Author-email: Brian Ruf <Brian@RufRisk.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/brian-ruf/ruf-common-python
+Project-URL: Repository, https://github.com/brian-ruf/ruf-common-python.git
+Project-URL: Documentation, https://github.com/brian-ruf/ruf-common-python#readme
+Project-URL: Issues, https://github.com/brian-ruf/ruf-common-python/issues
+Keywords: utilities,common,helpers
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: elementpath>=4.7.0
+Requires-Dist: pytz>=2025.2
+Requires-Dist: tzlocal>=5.3.1
+Requires-Dist: geopy>=2.4.1
+Requires-Dist: timezonefinder>=8.1.0
+Requires-Dist: aiohttp>=3.12.15
+Requires-Dist: boto3
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pycountry>=22.3.5
+Requires-Dist: html2text>=2020.1.16
+Requires-Dist: packaging>=23.1
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# COMMON PYTHON MODULES
+
+## Overview
+This is a collection of python modules I have created and use in several of my projects. This is just a convenient way for me to keep them in sync across projects. The repo is public so that it can be easily referenced by people using my public projects.
+
+Feedback welcome in the form of a [GitHub issue](https://github.com/brian-ruf/ruf-common-python/issues). While I will try to address issues in a timely matter, I only intend to invest in feature requests that align with my project work. Feel free to contribute backward compatible enhancements.
+
+## Dependencies
+
+Collectively, these modules rely on the following external libraries:
+
+- loguru
+- elementpath
+- pytz
+- tzlocal
+- geopy
+- timezonefinder
+- aiohttp
+- boto3
+- requests
+- pycountry
+- html2text
+- packaging
+- pyyaml
+
+## Setup
+
+
+
+To use this submodule in your GitHub repository:
+
+1. With your repository's `./src` folder as the default location, issue the following command:
+```
+git submodule add https://github.com/brian-ruf/common-python.git common
+```
+
+2. Import the library into your python modules:
+
+```python
+from common import * # to import all
+
+# OR
+
+from common import misc # import only one of the modules
+```
+
+## Modules
+
+The following modules are exposed to your application via the above instructions:
+
+- `aws.py`: Functions for interacting with AWS services
+- `country_code_converter.py`: Functions for converting between country code formats
+- `data.py`: Functions for managing and manipulating XML, JSON and YAML content
+- `database.py`: Functions for interacting with a database. These functions operate the same for all supported databases
+- `helper.py`: Various helper functions
+- `html_to_markdown.py`: Functions for converting HTML content to Markdown
+- `lfs.py`: Functions for interacting with the local file system (LFS)
+- `logging.py`: Logging configuration and utilities
+- `network.py`: Functions for network operations
+- `stats.py`: Statistical helper functions
+- `timezone_lookup.py`: Functions for timezone lookups based on location
+- `xml_formatter.py`: Functions for formatting XML content
+
+The following additional modules are present and support the above, but are not directly exposed:
+- `database_sqlite3.py`: Any database-specific interactions are collected in a single file for that database

ruf_common-1.0.1/README.md

@@ -0,0 +1,65 @@
+# COMMON PYTHON MODULES
+
+## Overview
+This is a collection of python modules I have created and use in several of my projects. This is just a convenient way for me to keep them in sync across projects. The repo is public so that it can be easily referenced by people using my public projects.
+
+Feedback welcome in the form of a [GitHub issue](https://github.com/brian-ruf/ruf-common-python/issues). While I will try to address issues in a timely matter, I only intend to invest in feature requests that align with my project work. Feel free to contribute backward compatible enhancements.
+
+## Dependencies
+
+Collectively, these modules rely on the following external libraries:
+
+- loguru
+- elementpath
+- pytz
+- tzlocal
+- geopy
+- timezonefinder
+- aiohttp
+- boto3
+- requests
+- pycountry
+- html2text
+- packaging
+- pyyaml
+
+## Setup
+
+
+
+To use this submodule in your GitHub repository:
+
+1. With your repository's `./src` folder as the default location, issue the following command:
+```
+git submodule add https://github.com/brian-ruf/common-python.git common
+```
+
+2. Import the library into your python modules:
+
+```python
+from common import * # to import all
+
+# OR
+
+from common import misc # import only one of the modules
+```
+
+## Modules
+
+The following modules are exposed to your application via the above instructions:
+
+- `aws.py`: Functions for interacting with AWS services
+- `country_code_converter.py`: Functions for converting between country code formats
+- `data.py`: Functions for managing and manipulating XML, JSON and YAML content
+- `database.py`: Functions for interacting with a database. These functions operate the same for all supported databases
+- `helper.py`: Various helper functions
+- `html_to_markdown.py`: Functions for converting HTML content to Markdown
+- `lfs.py`: Functions for interacting with the local file system (LFS)
+- `logging.py`: Logging configuration and utilities
+- `network.py`: Functions for network operations
+- `stats.py`: Statistical helper functions
+- `timezone_lookup.py`: Functions for timezone lookups based on location
+- `xml_formatter.py`: Functions for formatting XML content
+
+The following additional modules are present and support the above, but are not directly exposed:
+- `database_sqlite3.py`: Any database-specific interactions are collected in a single file for that database

ruf_common-1.0.1/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=64.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ruf-common"
+version = "1.0.1"
+description = "Common Python utilities"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Brian Ruf", email = "Brian@RufRisk.com" }]
+readme = "README.md"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+keywords = ["utilities", "common", "helpers"]
+dependencies = [
+    "loguru>=0.7.3",
+    "elementpath>=4.7.0",
+    "pytz>=2025.2",
+    "tzlocal>=5.3.1",
+    "geopy>=2.4.1",
+    "timezonefinder>=8.1.0",
+    "aiohttp>=3.12.15",
+    "boto3",
+    "requests>=2.31.0",
+    "pycountry>=22.3.5",
+    "html2text>=2020.1.16",
+    "packaging>=23.1",
+    "pyyaml>=6.0.2"
+]
+
+[project.urls]
+Homepage   = "https://github.com/brian-ruf/ruf-common-python"
+Repository = "https://github.com/brian-ruf/ruf-common-python.git"
+Documentation = "https://github.com/brian-ruf/ruf-common-python#readme"
+Issues = "https://github.com/brian-ruf/ruf-common-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["ruf_common*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["ruf_common"]
+omit = ["tests/*", "*/__pycache__/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+]

ruf_common-1.0.1/ruf_common/__init__.py

@@ -0,0 +1,27 @@
+from . import data
+from . import database
+from . import lfs
+from . import helper
+from . import network
+from . import aws
+from . import logging
+from . import stats
+from . import country_code_converter
+from . import html_to_markdown
+from . import timezone_lookup
+from . import xml_formatter
+
+__all__ = [
+    "data",
+    "database",
+    "lfs",
+    "helper",
+    "network",
+    "aws",
+    "logging",
+    "stats",
+    "country_code_converter",
+    "html_to_markdown",
+    "timezone_lookup",
+    "xml_formatter"
+]

ruf_common-1.0.1/ruf_common/aws.py

@@ -0,0 +1,206 @@
+""" 
+AWS S3 interaction functions
+"""
+# import time 
+# import json
+# import os
+# import sys
+# import urllib.request
+# import resource # used to monitor memory
+from loguru import logger
+
+import boto3    # Library: boto3 -- for interacting with AWS S3 buckets
+from botocore.exceptions import ClientError
+from typing import Any
+
+S3_BUCKETS = {}
+S3_CLIENT: Any = None
+S3_RESOURCE: Any = None
+
+# =============================================================================
+#  --- INTERACT WITH AN S3 BUCKET ---
+# =============================================================================
+# - s3_connection (aws_region, aws_key_id, aws_key, OPTIONAL use_client) -> Boolean
+# - s3_open_bucket (bucket_name, aws_region, aws_key_id, aws_key) -> Boolean
+# - s3_chkdir (bucket_name, path)  -> Boolean
+# - s3_chkfile (bucket_name, path) -> Boolean
+# - s3_mkdir (bucket_name, path) -> Boolean
+# - s3_get_file (bucket_name, file_name) -> Boolean, String
+# - s3_put_file (bucket_name, file_name, content)-> Boolean
+# - s3_rm_file (bucket_name, file)
+# =============================================================================
+
+# Establishes a connection to the S3 service 
+# Returns True if successful (S3 service is available/reachable in the specified region and access key is accepted as valid).False otherwise.
+def s3_connection(aws_region, aws_key_id, aws_key, use_client=False):
+    global S3_CLIENT, S3_RESOURCE
+    status = False
+    s3 = None
+    try:
+        if S3_CLIENT is None:
+            s3 = boto3.client(
+                service_name="s3",
+                region_name=aws_region,
+                aws_access_key_id=aws_key_id,
+                aws_secret_access_key=aws_key
+            )
+            S3_CLIENT = s3
+        else:
+            #  s3 = S3_CLIENT # cache it for reuse
+            pass
+
+        if S3_RESOURCE is None:
+            s3 = boto3.resource(
+                service_name="s3",
+                region_name=aws_region,
+                aws_access_key_id=aws_key_id,
+                aws_secret_access_key=aws_key
+            )
+            S3_RESOURCE = s3 # cache it for reuse
+        else:
+            # s3 = S3_CLIENT # cache it for reuse
+            pass
+        status = True
+    except Exception as error:
+        logger.error(f"Unable to connect to AWS S3 service in {aws_region}. Possible invalid key or blocked communication. ({type(error).__name__}) {str(error)}")
+    return status
+
+# Opens a connect to an S3 bucket
+# Returns True if successful (bucket is available and access is granted).False otherwise.
+# Once a bucket is open, its object is cached until the application halts 
+def s3_open_bucket(bucket_name, aws_region, aws_key_id, aws_key):
+    global S3_RESOURCE, S3_BUCKETS
+    status = False
+    if bucket_name not in S3_BUCKETS:
+        status = s3_connection(aws_region, aws_key_id, aws_key)
+        if status:
+            try:
+                status = False
+                if S3_RESOURCE is not None:
+                    s3_bucket = S3_RESOURCE.Bucket(bucket_name)
+                    status = True
+                    S3_BUCKETS[bucket_name] = s3_bucket # Cache the Resource connection to the Bucket
+            except ClientError as error:
+                logger.warning(f"Unable to connect to {bucket_name}: {error}")
+            except Exception as error:
+                logger.error(f"{bucket_name} S3 bucket not found or no access. ({type(error).__name__}) {str(error)}") #  .message)
+
+    return status 
+
+# Checks for the existence of a folder or file on an S3 bucket
+# Returns True if the folder is found
+# Returns False if the folder's existence could not be determined or 
+#               if there was an error creating the folder.
+def s3_chkdir(bucket_name, path):
+    global S3_BUCKETS
+    status = False
+    # status, s3 = s3_connection(aws_region, aws_key_id, aws_key, True)
+    if bucket_name in S3_BUCKETS:    
+        try:
+            for obj in S3_BUCKETS[bucket_name].objects.all(): 
+                if path == obj.key or path + "/" == obj.key:
+                    # logger.info(path + " found in S3 Bucket")
+                    status = True
+                    break
+            if not status:
+                # logger.info(path + " NOT found in S3 Bucket.")
+                pass
+        except Exception as error:
+            if type(error).__name__ == "RequestTimeTooSkewed":
+                logger.error("Local host's time is too far out of sync with AWS time. ** !! This is a common problem with WSL after the local host wakes from sleep. Fix time in the local time and try again.")
+            else:    
+                logger.error(f"Error checking folder on S3 bucket. ({type(error).__name__}) {str(error)}")
+    else:
+        logger.error("Attempt to check directory on S3 bucket before opening S3 bucket.")
+
+    return status 
+
+# Creates a folder on an S3 bucket
+# Returns True if the folder already exists or was created successfully
+# Returns False if the folder's existence could not be determined or 
+#               if there was an error creating the folder.
+def s3_mkdir(bucket_name, path):
+    global S3_BUCKETS
+    status = False
+    # status, s3 = s3_connection(aws_region, aws_key_id, aws_key, True)
+    if bucket_name in S3_BUCKETS:
+        status = s3_chkdir(bucket_name, path)
+        if not status:
+            try:
+                S3_BUCKETS[bucket_name].put_object(Key=path + "/")
+                status = True
+            except Exception as error:
+                logger.error(f"Problem on S3 creating {path} ({type(error).__name__}) {str(error)}")
+    else:
+        logger.error("Attempt to make directory on S3 bucket before opening S3 bucket.")
+    
+    return status
+
+# Gets a file from a named S3 bucket
+# Returns a boolean (true if successful, false if not) and actual file content
+def s3_get_file(bucket_name, file_name):
+    global S3_CLIENT
+    status = False
+    ret_value = ""
+    if S3_CLIENT is not None:
+        try:
+            content_object = S3_CLIENT.get_object(Bucket=bucket_name, Key=file_name)
+            ret_value = content_object['Body'].read().decode('utf-8')
+            status = True
+        except ClientError as e:
+            ret_value = ""
+            error_code = e.response["Error"]["Code"]
+            if error_code == "AccessDenied":
+                logger.error("Access Denied fetching " + file_name)
+            else: # error_code == "InvalidLocationConstraint":
+                logger.error(f"{e.response['Error']['Code']} fetching {file_name}: {e.response['Error']['Message']}")
+        except Exception as error:
+            ret_value = ""
+            logger.error(f"Problem fetching {file_name} in S3 bucket {bucket_name} ({type(error).__name__}) {str(error)}")
+    else:
+        logger.error("Attempt to get file on S3 bucket before opening S3 bucket.")
+
+    return status, ret_value
+
+# Saves a file to a named S3 bucket
+# Returns true if successful, false if not
+def s3_put_file(bucket_name, file_name, content):
+    global S3_CLIENT
+    status = False
+    if S3_CLIENT is not None:
+        try:
+            S3_CLIENT.put_object(Bucket=bucket_name, Key=file_name, Body=content, ContentEncoding="utf-8")
+            status = True
+        except ClientError as e:
+            # ['Error']['Code'] e.g. 'EntityAlreadyExists' or 'ValidationError'
+            # ['ResponseMetadata']['HTTPStatusCode'] e.g. 400
+            # ['ResponseMetadata']['RequestId'] e.g. 'd2b06652-88d7-11e5-99d0-812348583a35'
+            # ['Error']['Message'] e.g. "An error occurred (EntityAlreadyExists) ..."
+            # ['Error']['Type'] e.g. 'Sender'
+            error_code = e.response["Error"]["Code"]
+            if error_code == "AccessDenied":
+                logger.error("Access Denied saving " + file_name)
+            else: # error_code == "InvalidLocationConstraint":
+                logger.error(f"{e.response['Error']['Code']} saving {file_name}: {e.response['Error']['Message']}")
+        except Exception as error:
+            logger.error(f"Problem saving {file_name} in S3 bucket {bucket_name} ({type(error).__name__}) {str(error)}")
+    return status
+
+# Removes a file from an S3 bucket
+# Returns true if successful, false if not
+def s3_rm_file(bucket_name, file):
+    logger.error("S3 Remove File not implemented (common.py/s3_rm_file)")
+    return False
+
+
+
+# =============================================================================
+#  --- MAIN: Only runs if the module is executed stand-alone. ---
+# =============================================================================
+if __name__ == '__main__':
+    # Execute when the module is not initialized from an import statement.
+    logger.info("--- START ---")
+
+    logger.info("This contains functions common the OSCAL services capability. This module does nothing when run individually.")
+
+    logger.info("--- END ---")