cleek 0.0.1__tar.gz

cleek-0.0.1/.github/logo.svg

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="210mm"
+   height="297mm"
+   viewBox="0 0 210 297"
+   version="1.1"
+   id="svg1"
+   xml:space="preserve"
+   inkscape:version="1.4.2 (ebf0e940d0, 2025-05-08)"
+   sodipodi:docname="logo.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"><sodipodi:namedview
+     id="namedview1"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="mm"
+     inkscape:zoom="1.0670983"
+     inkscape:cx="326.58658"
+     inkscape:cy="450.28652"
+     inkscape:window-width="1920"
+     inkscape:window-height="1058"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1" /><defs
+     id="defs1" /><g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"><path
+       style="fill:#d7d7d7;fill-opacity:1;stroke:#000000;stroke-width:2.64583;stroke-linecap:butt;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
+       d="m 123.97327,107.1129 0.99178,74.38396 c -3.0629,24.49044 -11.44979,26.0363 -25.042598,26.28234 -13.4025,0.24258 -24.392025,-5.24806 -24.794653,-37.19199 l 9.174022,10.16581 c 0,0 0.141924,-6.88564 -0.743839,-10.16581 -1.100184,-4.07422 -2.885793,-8.10873 -5.557527,-11.37546 -2.676083,-3.27204 -10.063105,-7.71642 -10.063105,-7.71642 1.423901,37.71876 3.651485,65.47669 31.737151,63.97021 21.043929,-4.4e-4 31.303259,-15.49944 32.215429,-34.2944 0,0 1.9822,-48.1468 -1.22727,-73.90783 0,0 8.42379,-7.01297 9.51737,-9.079066 3.2554,-6.150409 -1.1452,-15.817931 -4.66328,-16.902904 -3.96153,-1.221735 -12.74815,-1.67797 -15.99148,0.904124 -2.57668,2.05136 -4.37578,9.902469 -4.20264,13.191448 0.89178,5.545348 5.51085,7.250588 8.65064,11.735988 z"
+       id="path1"
+       sodipodi:nodetypes="ccsccsscsccssssc" /><circle
+       style="opacity:1;fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:2.64583;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
+       id="path2"
+       cx="128.33102"
+       cy="93.26609"
+       r="6.1297264" /></g></svg>

cleek-0.0.1/.gitignore

@@ -0,0 +1,3 @@
+/*.egg-info/
+/build/
+/venv/

cleek-0.0.1/LICENSE

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

cleek-0.0.1/PKG-INFO

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: cleek
+Version: 0.0.1
+Summary: A simple task runner that generates command line interfaces
+Author-email: Peter Sutton <peter@foxdogstudio.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Trio
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Requires-Dist: rich
+Requires-Dist: trio
+Description-Content-Type: text/markdown
+
+<p align=center><img src=".github/logo.png" /></p>
+
+<p align=center><b>A simple task runner that generates command line interfaces</b></p>
+
+```Python
+from cleek import task
+
+@task
+def binary_op(x: int, y: int, op: Literal['add', 'sub'] = 'add') -> None:
+    print(x, op, y)
+```
+
+<p align=center><b>⬇️ Becomes ⬇️</b></p>
+
+```ShellSession
+$ clk binary-op -h
+usage: clk binary-op [-h] [-o {add,sub}] x y
+
+positional arguments:
+  x
+  y
+
+options:
+  -h, --help          show this help message and exit
+  -o, --op {add,sub}  default: add
+```
+
+## Install
+
+```ShellSession
+$ git clone https://github.com/petersuttondev/cleek.git
+$ pip install ./cleek
+```
+
+## Get Started
+
+1. Create a `cleeks.py` file in the root of your project and add tasks
+
+```Python
+from cleek import task
+
+@task
+def greet(name: str) -> None:
+    print(f'Hello, {name}!')
+```
+
+2. Run `clk` from anywhere inside your project to see your tasks.
+
+```ShellSession
+$ clk
+┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ Task  ┃ Usage               ┃
+┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│ greet │ clk greet [-h] name │
+└───────┴─────────────────────┘
+```
+
+3. Run `clk <task> -h` to print a task's help.
+
+```ShellSession
+$ clk greet
+usage: clk greet [-h] name
+
+positional arguments:
+  name
+
+options:
+  -h, --help  show this help message and exit
+```
+
+Finally, run a task:
+
+```ShellSession
+$ clk greet Peter
+Hello, Peter!
+```
+
+## Customizing Tasks
+
+* Set a task's name:
+
+```Python
+from cleek import task
+
+@task('bar')
+def foo() -> None:
+    print('foo function, bar task')
+```
+
+```ShellSession
+$ clk bar
+foo function, bar task
+```
+
+* Set a task's group:
+
+```Python
+from cleek import task
+
+@task(group='foo')
+def bar() -> None:
+    print('bar task in the foo group')
+```
+
+```ShellSession
+$ clk foo.bar
+bar task in the foo group
+```
+
+* Set a task's style. Used when listing tasks. See [Rich's Style
+  documentation](https://rich.readthedocs.io/en/stable/style.html) for supported
+  styles.
+
+```Python
+from cleek import task
+
+@task(style='red')
+def foo() -> None:
+    print("I'll be red if you run clk")
+```
+
+* To apply the same customization to many tasks, use `customize()` to create a
+  pre-configured version of the `task` decorator.
+
+```Python
+from cleek import customize
+
+foo_task = customize('foo', style='red')
+
+@foo_task
+def a() -> None: ...
+
+@foo_task
+def b() -> None: ...
+
+bar_task = customize('bar', style='blue')
+
+@bar_task
+def c() -> None: ...
+
+@bar_task
+def d() -> None: ...
+```
+
+```ShellSession
+$ clk
+┏━━━━━━━┳━━━━━━━━━━━━━━━━┓
+┃ Task  ┃ Usage          ┃
+┡━━━━━━━╇━━━━━━━━━━━━━━━━┩
+│ foo.a │ clk foo.a [-h] │
+│ foo.b │ clk foo.b [-h] │
+│ bar.c │ clk bar.c [-h] │
+│ bar.d │ clk bar.d [-h] │
+└───────┴────────────────┘
+```
+
+## Async Support
+
+Your tasks can be `async` functions:
+
+```Python
+from cleek import task
+import trio
+
+@task
+async def sleep(duration: float = 1.0) -> None:
+    print(f'Sleeping for {duration} seconds')
+    await trio.sleep(duration)
+```
+
+At the moment, `trio` is the only supported event loop. If want to use another
+event loop (I'm guessing `asyncio`), open an issue and I'll add it.
+
+## Finding Tasks
+
+1. If the environmental variable `CLEEKS_PATH` is set, `clk` treats the value
+   as a path and attempts to load it. If the load fails, `clk` fails.
+
+2. `clk` searches upwards from the current working directory towards the root
+   directory `/`, looking for a `cleeks.py` script or a `cleeks` package. A
+   script takes precedence over a package if both are found in the same
+   directory.
+
+## Supported Parameters
+
+If you get an error saying your task's parameters are not supported, open an
+issue containing the function signature and I'll add support.
+
+### `bool`
+
+* Keyword `bool` with `False` or `True` default
+
+```Python
+def foo(a: bool = False): ...
+def foo(a: bool = True): ...
+```
+
+* Keyword optional `bool` with `False`, `True`, or `None` default
+
+```Python
+def foo(a: bool | None = False): ...
+def foo(a: bool | None = True): ...
+def foo(a: bool | None = None): ...
+```
+
+### `str`
+
+* Positional `str`
+
+```Python
+def foo(a: str): ...
+```
+
+* Positional optional `str`
+
+```Python
+def foo(a: str | None): ...
+```
+ 
+* Keyword `str` with `str` default
+
+```Python
+def foo(a: str = 'a'): ...
+```
+
+* Keyword optional `str` with `str` or `None` default
+
+```Python
+def foo(a: str | None = 'a'): ...
+def foo(a: str | None = None): ...
+```
+
+* Variadic positional `str`
+
+```Python
+def foo(*a: str): ...
+```
+
+### `int`
+
+* Positional `int`
+
+```Python
+def foo(a: int): ...
+```
+
+* Keyword `int` with `int` default
+
+```Python
+def foo(a: int = 1): ...
+```
+
+* Keyword optional `int` with `int` or `None` default
+
+```Python
+def foo(a: int | None = 1): ...
+def foo(a: int | None = None): ...
+```
+
+### `float`
+
+* Positional `float`
+
+```Python
+def foo(a: float): ...
+```
+
+* Keyword `float` with `float` default
+
+```Python
+def foo(a: float = 1.0): ...
+```
+
+* Keyword optional `float` with `float` or `None` default
+
+```Python
+def foo(a: float | None = 1.0): ...
+def foo(a: float | None = None): ...
+```
+
+### `Literal[T]`
+
+* Positional `int` literal
+
+```Python
+@task
+def foo(a: Literal[1, 2, 3]): ...
+```
+
+* Positional `str` literal
+
+```Python
+@task
+def foo(a: Literal['a', 'b', 'c']): ...
+```
+
+* Keyword `int` literal with `int` default
+
+```Python
+@task
+def foo(a: Literal[1, 2, 3] = 1): ...
+```
+
+* Keyword `str` literal with `str` default
+
+```Python
+@task
+def foo(a: Literal['a', 'b', 'c'] = 'a'): ...
+```
+
+### Misc
+
+* Variadic positional `pathlib.Path`
+
+```Python
+from pathlib import Path
+
+@task
+def foo(*a: Path): ...
+```
+
+* Variadic positional `trio.Path`
+
+```Python
+from trio import Path
+
+@task
+def foo(*a: Path): ...
+```
+
+## Shell Completion
+
+`clk --completion` prints all task names to stdout.
+
+### zsh
+
+```Shell
+_complete_clk() {
+    reply=($(clk --completion))
+}
+
+compctl -K _complete_clk + -f clk