desertislandutils 0.1.0__tar.gz → 0.4.3__tar.gz

desertislandutils-0.4.3/.github/workflows/main.yml

@@ -0,0 +1,47 @@
+name: Merge Release Branch and Tag
+
+env:
+  ACTIONS_STEP_DEBUG: true
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+
+jobs:
+  tag-release:
+    runs-on: ubuntu-latest
+    if: |
+      github.event.pull_request.merged == true &&
+      startsWith(github.event.pull_request.head.ref, 'release/')
+    steps:
+      - name: Show PR info
+        run: |
+          echo "PR merged from: ${{ github.event.pull_request.head.ref }}"
+          echo "PR merged to: ${{ github.event.pull_request.base.ref }}"
+
+      - name: Checkout the repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate tag name
+        id: tag
+        run: |
+          release_branch="${{ github.event.pull_request.head.ref }}"
+          tag_name=$(echo "$release_branch" | sed -E 's/.*release.*([0-9]+\.[0-9]+\.[0-9]+).*/v\1/')
+          echo "release_tag_name=$tag_name" >> $GITHUB_OUTPUT
+          echo "Generated tag: $tag_name"
+
+      - name: Create and push tag
+        run: |
+          git config user.name gha-bot
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+          git tag --annotate "${{ steps.tag.outputs.release_tag_name }}" -m "release ${{ steps.tag.outputs.release_tag_name }}"
+          git push origin "${{ steps.tag.outputs.release_tag_name }}"
+          echo
+          echo "++++++++++++++++++++++++++++++++++++++++++++++++++++"
+          git log --graph --all -n10 --pretty=format:'%h %as %cn %x09%s %d'
+          echo "Tag "${{ steps.tag.outputs.release_tag_name }}" created and pushed"
+          echo "YOU CAN DELETE RELEASE BRANCH: $RELEASE_BRANCH"

desertislandutils-0.4.3/.github/workflows/release.yml

@@ -0,0 +1,71 @@
+name: Publish Release
+# create a release from the latest tag on MAIN or something
+
+env:
+  ACTIONS_STEP_DEBUG: true
+
+on:
+  workflow_run:
+    workflows: [Merge Release Branch and Tag]
+    types: [completed]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v5
+
+      - name: Get Latest Tag
+        id: get_tag
+        run: |
+          git branch --list
+          git log  --oneline --tags -n10 --pretty=format:'%h %as %cn %x09%s %d'
+          echo
+          echo "current ref is ${{ github.ref_name }}"
+          latest_tag="$(git describe --tags --abbrev=0)"
+          echo "latest tag: ${latest_tag}"
+          echo latest_tag="${latest_tag}" >> $GITHUB_OUTPUT
+
+      - name: Build UV Distribution from Latest Tag
+        run: |
+          git checkout "${{ steps.get_tag.outputs.latest_tag }}"
+          uv build
+
+      - name: Validate Tag Matches Version
+        run: |
+          tag="${{ steps.get_tag.outputs.latest_tag }}"
+          app_version="v$(uv version | awk '{print $2}')"
+          echo "Git tag: ${tag}"
+          echo "App version: ${app_version}"
+          if [[ "${tag}" != "${app_version}" ]]; then
+            echo "ERROR: Git tag '${tag}' does not match pyproject.toml version '${app_version}'"
+            echo "Developer must ensure release branch has matching version in pyproject.toml"
+            exit 1
+          fi
+          echo "Tag and version match"
+
+      - name: Create release from tag
+        id: create_release
+        uses: ncipollo/release-action@v1
+        with:
+          artifacts: "dist/*"
+          generateReleaseNotes: true
+          allowUpdates: true
+          tag: ${{ steps.get_tag.outputs.latest_tag }}
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_TOKEN }}
+
+      - name: Release URL Output
+        run: |
+          echo release URL: ${{ steps.create_release.outputs.html_url }}
+          echo PyPI: https://pypi.org/project/desertislandutils/

desertislandutils-0.4.3/.github/workflows/test.yml

@@ -0,0 +1,77 @@
+name: Test desertislandutils
+
+env:
+  ACTIONS_STEP_DEBUG: true
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches:
+      - '**'
+    paths-ignore:
+      - '**.md'
+  pull_request:
+    branches: [main]
+    paths-ignore: ['**.md']
+
+  # NOTE: workflow_dispatch only work on main
+  workflow_dispatch:
+    inputs:
+      note:
+        description: 'Describe why you are doing this'
+        required: false
+        default: 'no message'
+      manual_workflow_conclusion:
+        description: 'Insert success/failure for downstream'
+        required: false
+        default: ''
+        type: choice
+        options:
+        - ' '
+        - failure
+        - success
+
+jobs:
+  uv-run-tests:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v5
+
+      - name: UV Sync and Test
+        run: |
+          python --version
+          uv --version
+          uv sync --all-extras
+          uv run pytest --disable-warnings --verbose
+          echo "WARNING: Pytest Warnings are disabled"
+
+      - name: Get Latest Tag
+        id: get_tag
+        run: |
+          latest_tag="$(git ls-remote origin 'refs/tags/v*[0-9]' | awk -F'refs/tags/' '{print $2}' | sort -V | tail -1)"
+          echo latest_tag="${latest_tag}" >> $GITHUB_OUTPUT
+
+      - name: Get desertislandutils Version
+        id: app_version
+        run: |
+          app_version="$(uv version | awk '{print $2}')"
+          echo app_version="v${app_version}" >> $GITHUB_OUTPUT
+
+      - name: REFERENCE - Variables and Workflow Contexts
+        run: |
+          echo "workflow: ${{ github.workflow }}"
+          echo "job_id:  ${{ github.job }}"
+          echo "job status:  ${{ job.status }}"
+          echo "commit ref name:  ${{ github.ref_name }}"
+          echo "branch name: ${{ github.ref }}"
+          echo "latest tag: ${{ steps.get_tag.outputs.latest_tag }}"
+          echo "app version: ${{ steps.app_version.outputs.app_version }}"

desertislandutils-0.4.3/.gitignore

@@ -0,0 +1,148 @@
+# python gitignore standards
+# https://github.com/github/gitignore/blob/main/Python.gitignore
+
+# 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
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__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/

desertislandutils-0.4.3/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: desertislandutils
+Version: 0.4.3
+Summary: A collection of personal convenience utilities
+Project-URL: Homepage, https://github.com/mahiki/desertislandutils
+Project-URL: Repository, https://github.com/mahiki/desertislandutils
+Project-URL: Issues, https://github.com/mahiki/desertislandutils/issues
+Author-email: mahiki <mahiki@users.noreply.github.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: argparse>=1.4.0
+Requires-Dist: gitpython>=3.1.27
+Requires-Dist: pendulum>=3.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: ptpython>=3.0.23; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=7.2.2; extra == 'test'
+Description-Content-Type: text/markdown
+
+# desertislandutils
+
+A collection of personal convenience utilities for managing parallel directory structures and ISO week numbers. Written in Python because it's far better than shell scripting!
+
+## Installation
+
+Install globally using `uv`:
+
+```sh
+uv tool install desertislandutils
+```
+
+Update to the latest version:
+
+```sh
+uv tool upgrade desertislandutils
+```
+
+## The Utils
+
+### toobigdatadoc (`too`)
+
+Manage parallel directory structures for separating text files from large binary files and datasets. Creates symlinked folders under `HOME/{toobig|toodata|toodoc}`:
+
+- `toobig` - Large files excluded from backups
+- `toodata` - Small-ish data files  
+- `toodoc` - Binary files like PDFs and images
+
+```
+$HOME
+    |-- toobig
+        |-- # replicated folder paths with large files here, assume not to be backed up
+    |-- toodata
+        |-- # small-ish data files in support of the parallel root
+    |-- toodoc
+        |-- # usually pdfs or image files
+```
+
+**Usage:**
+
+```sh
+too --help
+
+usage: too [-h] {big,data,doc}
+
+Create symlinked parallel folders under HOME/{toobig|toodata|toodoc}, to
+contain data/binary files outside of git repo or away from source/text files.
+
+positional arguments:
+  {big,data,doc}  large files to exclude from backup, smallish datasets,
+                  binary files like pdf
+
+options:
+  -h, --help      show this help message and exit
+```
+
+### weeknumber (`wn`)
+
+Get ISO year week numbers in YYYY-WDD format. Default weekend day is Saturday.
+
+**Usage:**
+
+```sh
+wn --help
+
+ Usage: wn [OPTIONS] [DATE]                                                     
+                                                                                
+ ISO year week number of a date as YYYY-"W"WW. Default weekend day is Saturday.
+                                                                                
+ Example:                                                                       
+                                                                                
+ $> wn 'Jul 22 2020' --last                                                     
+                                                                                
+ 2020-W29                                                                       
+                                                                                
+╭─ Arguments ────────────────────────────────────────────────────────────────╮
+│   date      [DATE]  A text expression of date, ex: 'November 27', or      │
+│                     2112-07-29. Default is today's in current TZ.          │
+│                     [default: (dynamic)]                                   │
+╰────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ──────────────────────────────────────────────────────────────────╮
+│ --sunday              Week end is Saturday by default, this flag sets     │
+│                       Sunday weekend day (ISO standard).                   │
+│ --last                Give week number of most recently completed week    │
+│                       (overrides DATE argument).                           │
+│ --verbose      -v     Full parsed date details for verification.          │
+│ --install-completion  Install completion for the current shell.           │
+│ --show-completion     Show completion for the current shell, to copy it   │
+│                       or customize the installation.                       │
+│ --help                Show this message and exit.                          │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+**Examples:**
+
+```sh
+# Get current week number
+wn
+
+# Get week number for a specific date
+wn 'Jul 22'
+
+# Get last completed week number
+wn --last
+
+# Parse a specific date with details
+wn 'November 27 2024' --verbose
+```
+
+---
+
+## Development
+
+Built with modern Python tooling:
+
+- **Build system:** `uv`
+- **Deploy:** PyPI via GitHub Actions CI/CD
+- **Package manager:** `uv`
+
+### Setup
+
+```sh
+# Clone the repository
+git clone https://github.com/mahiki/desertislandutils.git
+cd desertislandutils
+
+# Install dependencies (including dev extras)
+uv sync --all-extras
+```
+
+### Testing
+
+```sh
+# Run tests
+just test
+
+# Or directly with uv
+uv run --extra test pytest --disable-warnings --verbose
+```
+
+### Local Development
+
+```sh
+# Run commands directly from source
+uv run wn --help
+uv run too --help
+```
+
+### Project Tasks
+
+See the `justfile` for available commands:
+
+```sh
+just --list
+```
+
+## License
+
+MIT

desertislandutils-0.4.3/README.md

@@ -0,0 +1,159 @@
+# desertislandutils
+
+A collection of personal convenience utilities for managing parallel directory structures and ISO week numbers. Written in Python because it's far better than shell scripting!
+
+## Installation
+
+Install globally using `uv`:
+
+```sh
+uv tool install desertislandutils
+```
+
+Update to the latest version:
+
+```sh
+uv tool upgrade desertislandutils
+```
+
+## The Utils
+
+### toobigdatadoc (`too`)
+
+Manage parallel directory structures for separating text files from large binary files and datasets. Creates symlinked folders under `HOME/{toobig|toodata|toodoc}`:
+
+- `toobig` - Large files excluded from backups
+- `toodata` - Small-ish data files  
+- `toodoc` - Binary files like PDFs and images
+
+```
+$HOME
+    |-- toobig
+        |-- # replicated folder paths with large files here, assume not to be backed up
+    |-- toodata
+        |-- # small-ish data files in support of the parallel root
+    |-- toodoc
+        |-- # usually pdfs or image files
+```
+
+**Usage:**
+
+```sh
+too --help
+
+usage: too [-h] {big,data,doc}
+
+Create symlinked parallel folders under HOME/{toobig|toodata|toodoc}, to
+contain data/binary files outside of git repo or away from source/text files.
+
+positional arguments:
+  {big,data,doc}  large files to exclude from backup, smallish datasets,
+                  binary files like pdf
+
+options:
+  -h, --help      show this help message and exit
+```
+
+### weeknumber (`wn`)
+
+Get ISO year week numbers in YYYY-WDD format. Default weekend day is Saturday.
+
+**Usage:**
+
+```sh
+wn --help
+
+ Usage: wn [OPTIONS] [DATE]                                                     
+                                                                                
+ ISO year week number of a date as YYYY-"W"WW. Default weekend day is Saturday.
+                                                                                
+ Example:                                                                       
+                                                                                
+ $> wn 'Jul 22 2020' --last                                                     
+                                                                                
+ 2020-W29                                                                       
+                                                                                
+╭─ Arguments ────────────────────────────────────────────────────────────────╮
+│   date      [DATE]  A text expression of date, ex: 'November 27', or      │
+│                     2112-07-29. Default is today's in current TZ.          │
+│                     [default: (dynamic)]                                   │
+╰────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ──────────────────────────────────────────────────────────────────╮
+│ --sunday              Week end is Saturday by default, this flag sets     │
+│                       Sunday weekend day (ISO standard).                   │
+│ --last                Give week number of most recently completed week    │
+│                       (overrides DATE argument).                           │
+│ --verbose      -v     Full parsed date details for verification.          │
+│ --install-completion  Install completion for the current shell.           │
+│ --show-completion     Show completion for the current shell, to copy it   │
+│                       or customize the installation.                       │
+│ --help                Show this message and exit.                          │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+**Examples:**
+
+```sh
+# Get current week number
+wn
+
+# Get week number for a specific date
+wn 'Jul 22'
+
+# Get last completed week number
+wn --last
+
+# Parse a specific date with details
+wn 'November 27 2024' --verbose
+```
+
+---
+
+## Development
+
+Built with modern Python tooling:
+
+- **Build system:** `uv`
+- **Deploy:** PyPI via GitHub Actions CI/CD
+- **Package manager:** `uv`
+
+### Setup
+
+```sh
+# Clone the repository
+git clone https://github.com/mahiki/desertislandutils.git
+cd desertislandutils
+
+# Install dependencies (including dev extras)
+uv sync --all-extras
+```
+
+### Testing
+
+```sh
+# Run tests
+just test
+
+# Or directly with uv
+uv run --extra test pytest --disable-warnings --verbose
+```
+
+### Local Development
+
+```sh
+# Run commands directly from source
+uv run wn --help
+uv run too --help
+```
+
+### Project Tasks
+
+See the `justfile` for available commands:
+
+```sh
+just --list
+```
+
+## License
+
+MIT