bear-epoch-time 1.0.1__tar.gz

bear_epoch_time-1.0.1/.bumpversion.cfg

@@ -0,0 +1,12 @@
+[bumpversion]
+current_version = 1.0.1
+
+[bumpversion:file:pyproject.toml]
+
+[bumpversion:file:README.md]
+search = # Bear Epoch Time v{current_version}
+replace = # Bear Epoch Time v{new_version}
+
+[bumpversion:file:src/bear_epoch_time/__init__.py]
+search = __version__ = "{current_version}"
+replace = __version__ = "{new_version}"

bear_epoch_time-1.0.1/.gitignore

@@ -0,0 +1,211 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python,macos,shell
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,macos,shell
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+.vscode/
+
+*.db

bear_epoch_time-1.0.1/AGENTS.md

@@ -0,0 +1,15 @@
+# Contributor Guide for AI Agents
+
+## Dev Environment Guidelines
+
+### Claude Only
+
+<antml:thinking_mode>interleaved</antml:thinking_mode><antml:max_thinking_length>16000</antml:max_thinking_length>
+
+- Python Version and Typing: Assume Python 3.12 or higher is being used. Because of that we SHOULD use the latest typing features available in Python 3.12 and later. Never use `Optional`, `Union`, or `Dict, List, Tuple` from `typing` module. Instead, use the built-in types directly, e.g., `list`, `dict`, `tuple`, and use `|` for union types. This is not an exhaustive list, so be thoughtful about any potentially deprecated types you might use. If you are not sure about something, ask the user.
+- Type Annotations: Use type annotations as often as possible. If a function has no return value, use `None` as the return type. If a function returns a value, use the appropriate type annotation but don't bend over backwards to make it perfect. If you are not sure about the type, use `Any` as a fallback but use this sparingly, see it as a failure and you should endeavor to avoid using `Any` as much as possible.
+- Docstrings: Use docstrings for most (95%) public functions and classes. The docstring should describe the purpose of the function or class, its parameters, and its return value. Use the Google style for docstrings. Because of this it is highly preferred to not use comments in the code unless absolutely necessary. If you feel like you need to use a comment, consider if the code can be refactored to make it more readable instead.
+- Imports: Use relative imports for everything (beyond the obvious imports for external packages) in this current package. Keep imports clean using `uv run isort src tests` and `uv run black src tests` to format the code in that order.
+- Endeavor to use a TDD approach when writing new code. Write tests first, then write the code to make the tests pass and then refactor the code to make it cleaner and more readable.
+- There is a `directory_structure.txt` file in the root of the repository that describes the directory structure of the project. Use this as a quick way to understand the project structure and where to place new files or modules.
+- While projects might partially use Poetry, UV is generally the preferred tool for managing dependencies and virtual environments. It is taking me some time to get used to it, so please bear with me. If you are not sure about something, ask the user.

bear_epoch_time-1.0.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: bear-epoch-time
+Version: 1.0.1
+Summary: Elegant epoch timestamp handling with timezone-aware operations, fluent API, and smart defaults for Python developers who hate datetime complexity.
+Author-email: chaz <bright.lid5647@fastmail.com>
+Requires-Python: >=3.10
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: pytz>=2025.2
+Requires-Dist: rich-tree-cli>=0.3.14
+Requires-Dist: rich>=14.0.0
+Requires-Dist: tzlocal>=5.3.1
+Description-Content-Type: text/markdown
+
+# Bear Epoch Time v1.0.1

bear_epoch_time-1.0.1/README.md

@@ -0,0 +1 @@
+# Bear Epoch Time v1.0.1

bear_epoch_time-1.0.1/TODO.md

@@ -0,0 +1,16 @@
+---
+tags: ["todo", "python", "module", "time", "pypi"]
+project_path: "/Users/chaz/Documents/repos/github/sicksubroutine/bear-epoch-time"
+---
+# bear-epoch-time 
+
+## Tasks 
+
+- [ ] Do a once over of everything with Codex (Hi! That is you! :D)
+	- [ ] Ensure there is good test coverage
+	- [ ] use Nox for ensure full Python Version coverage
+- [/] Return Default Constants for timezone related things (Basically have it use specific defaults for `BEAR` (the dev) and check for local values for everybody else) ([/] means the task is in progress)
+
+## Notes 
+
+

bear_epoch_time-1.0.1/directory_structure.txt

@@ -0,0 +1,34 @@
+  bear-epoch-time
+├──  .bumpversion.cfg (327 bytes) (12 lines)
+├──  .gitignore (3937 bytes) (211 lines)
+├──  .python-version (5 bytes) (1 lines)
+├──  AGENTS.md (2448 bytes) (15 lines)
+├──  directory_structure.txt (1794 bytes) (34 lines)
+├──  maskfile.md (819 bytes) (53 lines)
+├──  noxfile.py (1507 bytes) (70 lines)
+├──  pyproject.toml (855 bytes) (35 lines)
+├──  README.md (25 bytes) (1 lines)
+├──  TODO.md (554 bytes) (16 lines)
+├──  src
+│   └──  bear_epoch_time
+│       ├──  __init__.py (544 bytes) (25 lines)
+│       ├──  _helpers.py (2868 bytes) (92 lines)
+│       ├──  _time_class.py (11783 bytes) (327 lines)
+│       ├──  _time_class_legacy.py (11504 bytes) (315 lines)
+│       ├──  _timer.py (2349 bytes) (77 lines)
+│       ├──  _tools.py (456 bytes) (17 lines)
+│       ├──  _tz.py (4930 bytes) (172 lines)
+│       ├──  time_manager.py (8518 bytes) (238 lines)
+│       ├──  basic_logger
+│       │   ├──  __init__.py (117 bytes) (3 lines)
+│       │   ├──  logger.py (2459 bytes) (79 lines)
+│       │   └──  logger.pyi (948 bytes) (19 lines)
+│       └──  constants
+│           ├──  __init__.py (298 bytes) (8 lines)
+│           ├──  date_related.py (1003 bytes) (32 lines)
+│           └──  time_related.py (638 bytes) (22 lines)
+└──  tests
+    ├──  __init__.py (0 bytes) (0 lines)
+    ├──  test_basic_logger.py (3274 bytes) (93 lines)
+    ├──  test_epoch_timestamp.py (14011 bytes) (354 lines)
+    └──  test_time_parsing.py (992 bytes) (26 lines)

bear_epoch_time-1.0.1/maskfile.md

@@ -0,0 +1,58 @@
+# Python Project Mask File
+
+## clean
+
+> This command cleans the build artifacts
+
+```bash
+rm -rf dist/
+```
+
+## bump (patch_version)
+
+> Bump the version of the local project specifying the patch level: `minor`, `major`, `patch`
+
+```bash
+bump2version ${patch_version} --allow-dirty
+```
+
+## build
+
+> This command builds the project via uv
+
+```bash
+uv build
+```
+
+## test
+
+> This command runs the tests using pytest
+
+```bash
+pytest -s
+```
+
+## publish
+
+> This command publishes the package to PyPI officially, isn't that great?
+
+```bash
+if [ "${publish_location}" = "local" ]; then
+    twine upload -r local dist/* # uploads to a local repository
+else
+    export UV_PUBLISH_TOKEN=$(op read "op://Private/PyPI Prod/api_key")
+    uv publish --index pypi dist/* --token $UV_PUBLISH_TOKEN
+fi
+```
+
+## full (patch_version) (publish_location)
+
+> This command runs the full build and publish process
+
+```bash
+$MASK clean
+$MASK bump ${patch_version}
+$MASK build
+$MASK publish ${publish_location}
+pytest -s
+```

bear_epoch_time-1.0.1/noxfile.py

@@ -0,0 +1,70 @@
+import nox
+
+VERSIONS = ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+
+# @nox.session(venv_backend="uv", tags=["lint"])
+# def flake8(session):
+#     """Run flake8 linting"""
+#     session.install("flake8")
+
+#     session.run(
+#         "flake8",
+#         ".",
+#         "--count",
+#         "--select=E9,F63,F7,F82",
+#         "--show-source",
+#         "--statistics",
+#         "--exclude=.venv,.nox",
+#     )
+
+#     session.run(
+#         "flake8",
+#         ".",
+#         "--count",
+#         "--exit-zero",
+#         "--max-complexity=10",
+#         "--max-line-length=127",
+#         "--statistics",
+#         "--exclude=.venv,.nox",
+#     )
+
+
+# @nox.session(venv_backend="uv", tags=["lint"])
+# def isort(session):
+#     """Check import sorting with isort"""
+#     session.install("isort")
+#     session.run(
+#         "isort",
+#         ".",
+#         "--check-only",
+#         "--diff",
+#         "--skip",
+#         ".venv",
+#         "--skip",
+#         ".nox",
+#         "--line-length",
+#         "120",
+#     )
+
+
+# @nox.session(venv_backend="uv", tags=["lint"])
+# def black(session):
+#     """Check formatting with black"""
+#     session.install("black")
+#     session.run(
+#         "black",
+#         ".",
+#         "--check",
+#         "--diff",
+#         "--extend-exclude=.venv|.nox",
+#         "-l",
+#         "120",
+#     )
+
+
+@nox.session(python=VERSIONS, venv_backend="uv")
+def test_all_tests(session):
+    session.install("-e", ".")
+    session.install("pytest")
+    session.run("pytest")

bear_epoch_time-1.0.1/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "bear-epoch-time"
+version = "1.0.1"
+description = "Elegant epoch timestamp handling with timezone-aware operations, fluent API, and smart defaults for Python developers who hate datetime complexity."
+readme = "README.md"
+authors = [
+    { name = "chaz", email = "bright.lid5647@fastmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "python-dateutil>=2.9.0.post0",
+    "pytz>=2025.2",
+    "rich>=14.0.0",
+    "rich-tree-cli>=0.3.14",
+    "tzlocal>=5.3.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "black>=25.1.0",
+    "bump2version>=1.0.1",
+    "flake8>=7.2.0",
+    "isort>=6.0.1",
+    "nox>=2025.5.1",
+    "pytest>=8.4.0",
+]
+
+[tool.pytest.ini_options]
+markers = [
+    "visual: marks tests as visual verification tests (deselect with '-m \"not visual\"')"
+]

bear_epoch_time-1.0.1/src/bear_epoch_time/__init__.py

@@ -0,0 +1,25 @@
+__version__ = "1.0.1"
+
+import sys
+
+if sys.version_info < (3, 11):
+    from ._time_class_legacy import EpochTimestamp
+else:
+    from ._time_class import EpochTimestamp
+
+from ._timer import TimerData, create_timer, timer
+from ._tools import add_ord_suffix
+from .constants.date_related import DATE_FORMAT, DATE_TIME_FORMAT
+from .time_manager import TimeTools
+
+__all__ = [
+    "EpochTimestamp",
+    "TimerData",
+    "create_timer",
+    "timer",
+    "TimeTools",
+    "add_ord_suffix",
+    "DATE_FORMAT",
+    "DATE_TIME_FORMAT",
+    "__version__",
+]

bear_epoch_time-1.0.1/src/bear_epoch_time/_helpers.py

@@ -0,0 +1,92 @@
+import re
+from datetime import timedelta
+
+from .constants.time_related import (SECONDS_IN_DAY, SECONDS_IN_HOUR,
+                                     SECONDS_IN_MINUTE, SECONDS_IN_MONTH)
+
+
+def convert_to_seconds(time_str: str) -> int:
+    """Convert a time string to seconds.
+
+    Examples
+    --------
+    >>> convert_to_seconds("1M 30m")
+    2610000
+
+    Notes
+    -----
+    * ``M`` or ``mo`` denotes **months**.
+    * ``m`` denotes **minutes**.
+    """
+
+    time_parts: list[tuple[str, str]] = re.findall(r"(\d+)\s*(M|mo|[dhms])", time_str)
+    total_seconds = 0
+    for value, unit in time_parts:
+        if not value.isdigit():
+            raise ValueError(f"Invalid time value: {value}")
+        value = int(value)
+
+        if unit == "M" or unit.lower() == "mo":
+            total_seconds += value * SECONDS_IN_MONTH
+        elif unit == "d":
+            total_seconds += value * SECONDS_IN_DAY
+        elif unit == "h":
+            total_seconds += value * SECONDS_IN_HOUR
+        elif unit == "m":
+            total_seconds += value * SECONDS_IN_MINUTE
+        elif unit == "s":
+            total_seconds += value
+        else:
+            raise ValueError(f"Invalid time unit: {unit}")
+    return total_seconds
+
+
+def timedelta_to_seconds(td: timedelta) -> int:
+    """Convert a timedelta object to seconds."""
+    if not isinstance(td, timedelta):
+        raise ValueError("Input must be a timedelta object")
+    return int(td.total_seconds())
+
+
+def convert_to_milliseconds(time_str: str) -> int:
+    return convert_to_seconds(time_str) * 1000
+
+
+def milliseconds_to_time(milliseconds: int) -> str:
+    """Convert milliseconds to a human-readable time string."""
+    if milliseconds < 0:
+        raise ValueError("Milliseconds cannot be negative")
+    seconds = milliseconds // 1000
+    return seconds_to_time(seconds)
+
+
+def seconds_to_timedelta(seconds: int) -> timedelta:
+    """Convert seconds to a timedelta object."""
+    if seconds < 0:
+        raise ValueError("Seconds cannot be negative")
+    return timedelta(seconds=seconds)
+
+
+def seconds_to_time(seconds: int) -> str:
+    """Convert seconds to a human-readable time string.
+
+    Months are represented with ``M`` while minutes use ``m``.
+    """
+    if seconds < 0:
+        raise ValueError("Seconds cannot be negative")
+    months, remainder = divmod(seconds, SECONDS_IN_MONTH)
+    days, remainder = divmod(remainder, SECONDS_IN_DAY)
+    hours, remainder = divmod(remainder, SECONDS_IN_HOUR)
+    minutes, seconds = divmod(remainder, SECONDS_IN_MINUTE)
+    time_parts = []
+    if months > 0:
+        time_parts.append(f"{months}M")
+    if days > 0:
+        time_parts.append(f"{days}d")
+    if hours > 0:
+        time_parts.append(f"{hours}h")
+    if minutes > 0:
+        time_parts.append(f"{minutes}m")
+    if seconds > 0:
+        time_parts.append(f"{seconds}s")
+    return " ".join(time_parts)