desertislandutils 0.1.0__tar.gz → 0.4.2__tar.gz

desertislandutils-0.4.2/.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.2/.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.2/.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.2/.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.2/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: desertislandutils
+Version: 0.4.2
+Summary: A collection of personal convenience utilities
+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
+Refactoring my convenience utility bash scripts into python for learning and profit. Deployed for MacOS via homebrew, its really far better than shell scripting, yuck!
+
+## INSTALL
+    brew install mahiki/tap/desertislandutils
+
+## THE UTILS
+### toobigdatadoc
+I like to keep text files in one directory system, with supporting data files and binary documents in parallel directories from the home folder: `toobig`, `toodata`, `toodoc`. For example, its easy to exclude the whole `toobig` directory structure from backups, since there is nothing but huge files here.
+
+    $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
+
+```sh
+$> too --help
+usage: too [-h] {big,data,doc}
+
+Create symlinked parallel folders 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
+
+optional arguments:
+  -h, --help      show this help message and exit
+Kehena segovia: ~
+```
+
+### weeknumber
+```sh
+wn --help
+
+ Usage: wn [OPTIONS] [DATE]
+
+ ISO year week number of a date as YYYY-WDD. Default weekend day is Sat.
+ Example:
+ $> wn 'Jul 22'
+ 2023-W29
+
+╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────╮
+│   date      [DATE]  A text expression of date, ex: 'November 27', or 2112-07-29 [default: (dynamic)]          │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ --sunday                     Weekend is Saturday by default, this flag sets Sunday weekend day.               │
+│ --last                       Give week number of most recently completed week (overrides DATE argument).      │
+│ --verbose       --no-verbose [default: no-verbose]                                                            │
+│ --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.                                                      │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+----------
+## DEVELOPMENT
+>Trying to automate the merge tag homebrew tap repo upgrade thing. Its not going great.
+
+* build: poetry
+* deploy: poetry -> pypi -> homebrew
+* github CI actions
+
+### JUSTFILE
+>Best documentation is in the Just taskrunner `justfile`.
+
+```sh
+just info
+
+just wn --help
+
+# also direct into poetry environment
+poetry shell
+(desertislandutils)> wn --help
+```
+
+### Testing
+    just test

desertislandutils-0.4.2/README.md

@@ -0,0 +1,79 @@
+# desertislandutils
+Refactoring my convenience utility bash scripts into python for learning and profit. Deployed for MacOS via homebrew, its really far better than shell scripting, yuck!
+
+## INSTALL
+    brew install mahiki/tap/desertislandutils
+
+## THE UTILS
+### toobigdatadoc
+I like to keep text files in one directory system, with supporting data files and binary documents in parallel directories from the home folder: `toobig`, `toodata`, `toodoc`. For example, its easy to exclude the whole `toobig` directory structure from backups, since there is nothing but huge files here.
+
+    $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
+
+```sh
+$> too --help
+usage: too [-h] {big,data,doc}
+
+Create symlinked parallel folders 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
+
+optional arguments:
+  -h, --help      show this help message and exit
+Kehena segovia: ~
+```
+
+### weeknumber
+```sh
+wn --help
+
+ Usage: wn [OPTIONS] [DATE]
+
+ ISO year week number of a date as YYYY-WDD. Default weekend day is Sat.
+ Example:
+ $> wn 'Jul 22'
+ 2023-W29
+
+╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────╮
+│   date      [DATE]  A text expression of date, ex: 'November 27', or 2112-07-29 [default: (dynamic)]          │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ --sunday                     Weekend is Saturday by default, this flag sets Sunday weekend day.               │
+│ --last                       Give week number of most recently completed week (overrides DATE argument).      │
+│ --verbose       --no-verbose [default: no-verbose]                                                            │
+│ --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.                                                      │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+----------
+## DEVELOPMENT
+>Trying to automate the merge tag homebrew tap repo upgrade thing. Its not going great.
+
+* build: poetry
+* deploy: poetry -> pypi -> homebrew
+* github CI actions
+
+### JUSTFILE
+>Best documentation is in the Just taskrunner `justfile`.
+
+```sh
+just info
+
+just wn --help
+
+# also direct into poetry environment
+poetry shell
+(desertislandutils)> wn --help
+```
+
+### Testing
+    just test

desertislandutils-0.4.2/base.justfile

@@ -0,0 +1,46 @@
+# Default justfile for import
+
+# just --list
+[private]
+ac3e01d:
+  @just --justfile base.justfile --list --unsorted --list-heading $'Default Justfile for Imports\n'
+
+# color code definitions for use in any justfile
+[private]
+colordefs:
+  @echo
+  @echo "{{BCY}}Terminal color code definitions included for use in any justfile{{NC}}"
+  @echo '    For example, {{{{BCY}} gives:' 
+  @echo "    {{BCY}}Bright Cyan{{NC}}"
+  @echo
+
+# show the color codes
+colortest:
+  @echo "            {{NC}}NC{{NC}}"
+  @echo "   {{BK}}BK{{NC}}               {{BL}}BL{{NC}}"
+  @echo "   {{BBK}}BBK{{NC}}              {{BBL}}BBL{{NC}}"
+  @echo "   {{RD}}RD{{NC}}               {{MG}}MG{{NC}}"
+  @echo "   {{BRD}}BRD{{NC}}              {{BMG}}BMG{{NC}}"
+  @echo "   {{GR}}GR{{NC}}               {{CY}}CY{{NC}}"
+  @echo "   {{BGR}}BGR{{NC}}              {{BCY}}BCY{{NC}}"
+  @echo "   {{YW}}YW{{NC}}               {{WT}}WT{{NC}}"
+  @echo "   {{BYW}}BYW{{NC}}              {{BWT}}BWT{{NC}}"
+
+# color decorations
+BK  := '\033[0;30m'   # Black        
+BBK := '\033[1;30m'   # Bright Gray  
+RD  := '\033[0;31m'   # Red          
+BRD := '\033[1;31m'   # Bright Red   
+GR  := '\033[0;32m'   # Green        
+BGR := '\033[1;32m'   # Bright Green 
+YW  := '\033[0;33m'   # Yellow       
+BYW := '\033[1;33m'   # Bright Yellow
+BL  := '\033[0;34m'   # Blue         
+BBL := '\033[1;34m'   # Light Blue   
+MG  := '\033[0;35m'   # Magenta      
+BMG := '\033[1;35m'   # Light Purple 
+CY  := '\033[0;36m'   # Cyan         
+BCY := '\033[1;36m'   # Light Cyan   
+WT  := '\033[0;37m'   # White        
+BWT := '\033[1;37m'   # Light White  
+NC := '\033[0m'

desertislandutils-0.4.2/justfile

@@ -0,0 +1,78 @@
+import './base.justfile'
+set positional-arguments := true
+
+# just --list
+[private]
+default:
+  @just --list --unsorted --list-heading $'UV development workflow commands:\n'
+
+# 'uv run' pass thru command
+uv *args:
+  @uv run "$@"
+
+# pass thru
+pass *args:
+  {{args}}
+
+# ptpython REPL in uv environment
+repl:
+  @uv run ptpython
+
+# instructions to bump version number
+bump level="patch":
+  @echo
+  @echo "   {{BCY}}Bumping version with {{YW}}uv version --bump [patch|minor|major]{{NC}}"
+  @echo
+  @uv version --bump {{ level }}
+
+# pytest
+test *args:
+  @echo
+  @echo "            ✙✙✙✙✙✙✙✙    TESTING    ✙✙✙✙✙✙✙✙"
+  uv sync --all-extras
+  uv run pytest --disable-warnings --verbose {{args}}
+
+# INFO: develop, build, deploy
+info:
+  @echo
+  @echo "   {{BCY}}Workflow to develop python scripts and deploy via uv tool{{NC}}"
+  @echo
+  @echo "       {{CY}}1.{{NC}} Develop/commit on dev"
+  @echo "       {{CY}}2.{{NC}} just test"
+  @echo "       {{CY}}3.{{NC}} just bump"
+  @echo "       {{CY}}4.{{NC}} git checkout -b release/x.y.z"
+  @echo "           {{CY}}*{{NC}} final TESTS and debug"
+  @echo "           {{CY}}*{{NC}} git push --set-upstream origin release/x.y.z"
+  @echo "           {{CY}}*{{NC}} PR 'release/x.y.z' for CI/CD tests (click link to open PR)"
+  @echo "           {{CY}}*{{NC}} debug GHA tests"
+  @echo "           {{CY}}*{{NC}} GHA-bot auto-merge to main and tag"
+  @echo "       {{CY}}5.{{NC}} Publish to PyPI: uv publish"
+  @echo "       {{CY}}6.{{NC}} Install globally: uv tool install desertislandutils"
+  @echo "       {{CY}}7.{{NC}} git delete that release branch or maybe GHA does for you"
+  @echo
+  @echo "   {{BCY}}Running utils in uv environment{{NC}}"
+  @echo
+  @echo "       {{GR}}just uv wn"
+  @echo "       {{GR}}just uv wn --help"
+  @echo "       {{GR}}just uv too --help"
+  @echo
+
+# sync dependencies
+sync:
+  uv sync
+
+# sync with dev and test dependencies
+sync-all:
+  uv sync --all-extras
+
+# build package
+build:
+  uv build
+
+# install as global tool (from local source)
+install-local:
+  uv tool install --editable .
+
+# uninstall global tool
+uninstall:
+  uv tool uninstall desertislandutils