desertislandutils 0.1.0__py3-none-any.whl → 0.4.3__py3-none-any.whl

desertislandutils-0.4.3.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/toobigdatadoc/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/toobigdatadoc/too.py,sha256=PF8ycDOfrk6yzlQkajAEYQOB2G7FGsBWvHcDMobdwTg,2848
+src/weeknumber/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/weeknumber/wn.py,sha256=uqKt-oXhLKkKeK35xyjx1vakjAIKVZniQksycbF1PE8,2908
+desertislandutils-0.4.3.dist-info/METADATA,sha256=UAK_ixp1LWc102kF_RKhIOclkmIXs6OCmMjVkSmqKFE,5827
+desertislandutils-0.4.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+desertislandutils-0.4.3.dist-info/entry_points.txt,sha256=5TRbM9NEaDJ_d-cfZprBLYMhblbwTp2Zn966FTkwVM8,78
+desertislandutils-0.4.3.dist-info/RECORD,,

{desertislandutils-0.1.0.dist-info → desertislandutils-0.4.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry 1.0.8
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

desertislandutils-0.4.3.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+too = src.toobigdatadoc.too:main
+wn = src.weeknumber.wn:app

src/toobigdatadoc/__init__.py

@@ -1 +0,0 @@
-__version__ = '0.1.0'

src/toobigdatadoc/too.py

@@ -1,36 +1,42 @@
-"""Create a symlinked folder in the current directory pointing to 'too' project root directory.
+"""A command line utility to create a symlinked folder in the current directory, pointing to the 'too' project root directory.
 
-I like to keep source code and notes as text files, with associated documents, data, and images stored separately on a parallel file structure. The main benefits are browsing through directories and scanning the notes contents visually, and looking through filenames without a lot of clutter.
+For the purpose of keeping source code and notes as text files, with associated documents, data, and images stored separately on a parallel file structure. The main benefits are browsing through directories and scanning the notes contents visually, and looking through filenames without a lot of clutter.
+
+NOTE: git repos can be moved anywhere, because their path is uniquely definied by root name.
 
 Usage:
-          
+
 too big|data|doc
 """
 # TODO: [--verbose, -v] version print 
-#   folder created: ../../../../../toodoc/datasci/biq/biq-206/bigtest
-#   symlink:        doc -> ../../../../../toodoc/datasci/biq/biq-206/bigtest
+#   folder created: $HOME/toodoc/datasci/biq/biq-206/bigtest
+#   symlink:        doc -> $HOME/toodoc/datasci/biq/biq-206/bigtest
 
 from argparse import ArgumentParser
 from git import Repo, exc
 from pathlib import Path
 
-def call_the_parser():
+POSITIONAL_ARGS = {
+    'big': 'toobig'
+    , 'data': 'toodata'
+    , 'doc': 'toodoc'
+    }
+
+def cli_parser(args = None):
+    if args: args = [args]       # must do for test calls
+    arg_choices = list(POSITIONAL_ARGS)
     parser = ArgumentParser(
-            prog = "too"
-            , description = "Create symlinked parallel folders to contain data/binary files outside of\n git repo or away from source/text files."
+        prog = "too"
+        , description = "Create symlinked parallel folders under HOME/{toobig|toodata|toodoc}, to contain data/binary files outside of\n git repo or away from source/text files."
         )
-
     parser.add_argument(
-        'arg1'
-        , choices = ['big', 'data', 'doc']
+        'too_dir'
+        , choices = arg_choices
         , help = "large files to exclude from backup, smallish datasets, binary files like pdf"
         )
+    args = parser.parse_args(args)
+    return args.too_dir
 
-    args = parser.parse_args()
-
-    return args.arg1
-
-# TODO: combine is_git_repo && repo_root
 def is_git_repo(path):
     try:
         _ = Repo(path, search_parent_directories=True)
@@ -45,18 +51,9 @@ def repo_root(repo_path):
     except exc.InvalidGitRepositoryError:
         return None
 
-def top_dir_rel_path(tbdd):
-    switch = {
-        'big': 'toobig'
-        , 'data': 'toodata'
-        , 'doc': 'toodoc'
-        }
-    topname = switch.get(tbdd, "ERROR")
-    relative_path_home = str(Path.cwd().relative_to(Path.home()))
-    levels_home = len(relative_path_home.split('/'))
-    dots_home = '../' * levels_home
-
-    return Path(dots_home) / topname
+def top_dir_path(tbdd):
+    topname = POSITIONAL_ARGS.get(tbdd, "ERROR")
+    return Path.home() / topname
 
 def make_topdir_and_link(new_path):
     try:
@@ -68,21 +65,23 @@ def make_topdir_and_link(new_path):
     except FileExistsError:
         print("Symlink already exists")
 
-def too_rel_path(any_path):
+def too_path(any_path):
     if is_git_repo(any_path):
         repo_root_path = repo_root(any_path)
         path_from_root = any_path.relative_to(repo_root_path)
-        return top_dir_rel_path(TOPDIR_NAME) / repo_root_path.name / path_from_root
+        return top_dir_path(TOPDIR_NAME) / repo_root_path.name / path_from_root
     else:
         path_from_home = any_path.relative_to(Path.home())
-        return top_dir_rel_path(TOPDIR_NAME) / path_from_home
+        return top_dir_path(TOPDIR_NAME) / path_from_home
 
 
-def main():
+def main(too_dir = None):
     global TOPDIR_NAME
-    TOPDIR_NAME = call_the_parser()
 
-    make_topdir_and_link(too_rel_path(Path.cwd()))
+    too_dir = cli_parser(too_dir)
+    TOPDIR_NAME = too_dir
+
+    make_topdir_and_link(too_path(Path.cwd()))
 
 if __name__ == "__main__":
     main()

src/weeknumber/wn.py

@@ -0,0 +1,85 @@
+"""
+CLI utility that gives the ISO reporting week for a given date.
+Option allows week ending day of Saturday or Sunday.
+Option for week number of most recently completed week.
+Example: wn --last
+    2023-W48
+"""
+
+import pendulum
+from pendulum.parsing.exceptions import ParserError
+import typer
+from typing_extensions import Annotated, Optional, List
+
+app = typer.Typer()
+
+def input_date_validate(value: str):
+    try:
+        pendulum.parse(value, strict=False)
+    except ParserError as ex:
+        raise typer.BadParameter(f"{ex}, try YYYY-MM-DD format.")
+    return value
+
+def today_datestring():
+    return pendulum.now().to_date_string()
+
+def week_number_string(date, sunday_weekend = False):
+    if sunday_weekend:
+        return date.strftime("%G-W%V")
+    else:
+        return date.add(days=1).strftime("%G-W%V")
+
+def verbose_output(date, parsed_date, sunday_weekend, last_week):
+    weekend_day = "Sunday" if sunday_weekend else "Saturday"
+
+    if sunday_weekend:
+        weekend_date = parsed_date.add(days=-1).next(pendulum.SUNDAY)
+    else:
+        weekend_date = parsed_date.add(days=-1).next(pendulum.SATURDAY)
+
+    if last_week: weekend_date = weekend_date.subtract(weeks=1)
+
+    typer.echo(f"Input date string: {date}")
+    typer.echo(f"Timezone:          {pendulum.now().timezone.name}")
+    typer.echo(f"Parsed date:       {parsed_date.to_date_string()}")
+    typer.echo(f"Last week flag:    {last_week}")
+    typer.echo(f"Week end day:      {weekend_day}")
+    typer.echo(f"Week end date:     {weekend_date.to_date_string()}")
+
+
+@app.command()
+def main(
+    date: Annotated[str
+        , typer.Argument(
+            callback=input_date_validate
+            , help="A text expression of date, ex: 'November 27', or 2112-07-29. Default is today's in current TZ."
+            , default_factory=today_datestring)]
+    , sunday_weekend: Annotated[bool
+        , typer.Option(
+            "--sunday"
+            , help="Week end is Saturday by default, this flag sets Sunday weekend day (ISO standard).")] = False
+    , last_week: Annotated[bool
+        , typer.Option(
+            "--last"
+            , help="Give week number of most recently completed week (overrides DATE argument).")] = False
+    , verbose: Annotated[bool
+        , typer.Option(
+            "--verbose", "-v"
+            , help="Full parsed date details for verification."
+        )] = False
+    ):
+    """
+    ISO year week number of a date as YYYY-"W"WW. Default weekend day is Saturday.\n
+    Example:\n
+    $> wn 'Jul 22 2020' --last\n
+    2020-W29
+    """
+    parsed_date = pendulum.parse(date, strict=False)
+    if verbose: verbose_output(date, parsed_date, sunday_weekend, last_week)
+
+    if last_week:
+        result = week_number_string(parsed_date.subtract(weeks=1), sunday_weekend=sunday_weekend)
+    else:
+        result = week_number_string(parsed_date, sunday_weekend=sunday_weekend)
+
+    typer.echo(result)

desertislandutils-0.1.0.dist-info/METADATA

@@ -1,14 +0,0 @@
-Metadata-Version: 2.1
-Name: desertislandutils
-Version: 0.1.0
-Summary: A collection of personal convenience utilities
-License: MIT
-Author: mahiki
-Author-email: mahiki@users.noreply.github.com
-Requires-Python: >=3.9,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.9
-Requires-Dist: GitPython (>=3.1.27,<4.0.0)
-Requires-Dist: argparse (>=1.4.0,<2.0.0)

desertislandutils-0.1.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-src/toobigdatadoc/__init__.py,sha256=IMjkMO3twhQzluVTo8Z6rE7Eg-9U79_LGKMcsWLKBkY,22
-src/toobigdatadoc/too.py,sha256=0um45KMmed7mNq_PKpj5ZcbDi9pTBmd5tTdylf0xm8E,2794
-desertislandutils-0.1.0.dist-info/entry_points.txt,sha256=WQtlzk18d_KMRIIwBI-vb8gj2Vw0fQnxNsSQKur_S7k,50
-desertislandutils-0.1.0.dist-info/WHEEL,sha256=DA86_h4QwwzGeRoz62o1svYt5kGEXpoUTuTtwzoTb30,83
-desertislandutils-0.1.0.dist-info/METADATA,sha256=SkcYaP9TBU5gWJjeTtO4odFNn_JjfBVXAU6NZuO9JrE,503
-desertislandutils-0.1.0.dist-info/RECORD,,

desertislandutils-0.1.0.dist-info/entry_points.txt

@@ -1,3 +0,0 @@
-[console_scripts]
-too=src.toobigdatadoc.too:main
-