pullup 0.0.6__tar.gz → 0.0.7__tar.gz

pullup-0.0.7/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: pullup
+Version: 0.0.7
+Summary: build, release, and deploy projects
+Project-URL: Repository, https://github.com/vedicreader/pullup
+Project-URL: Documentation, https://vedicreader.github.io/pullup
+Author-email: Karthik Rajgopal <karthik.rajgopal@hotmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: jupyter,nbdev,notebook,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Requires-Dist: cfeasy>=0.0.4
+Requires-Dist: dockeasy>=0.0.5
+Requires-Dist: fastcore>=1.8.17
+Requires-Dist: gheasy>=0.0.10
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: ptymini>=0.0.5
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: vpseasy>=0.0.18
+Description-Content-Type: text/markdown
+
+# pullup
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+pullup is the engine behind a release and deploy panel. Point it at a project folder and it tells you what kind of project it is (an nbdev library, a plain Python package, a Rust crate and so on) and which commands release it. It then runs those commands in a terminal you can watch, and stops at the first one that fails. The same machinery runs the deploy of a web app to a virtual private server (VPS). pullup also reads the GitHub Actions workflows in the repository, writes new ones, and lists the Hetzner servers and Cloudflare tunnels the project uses.
+
+Every public call returns plain dictionaries and lists, so a user interface can draw them and a test can compare them. The work that talks to GitHub, Docker, Hetzner and Cloudflare is done by four sibling libraries: gheasy, dockeasy, vpseasy and cfeasy.
+
+## Install
+
+``` sh
+pip install pullup
+```
+
+This also installs gheasy, dockeasy, vpseasy and cfeasy. None of them is imported until a call needs it, so reading a project or running a release does not load them.
+
+## What kind of project is this
+
+A release flow is the ordered list of commands that publishes one kind of project. An nbdev library is released with `nbdev_prepare`, `nbdev_bump_version`, `nbdev_release_gh` and `nbdev_pypi`. A plain Python package and a Rust crate each have a different list. [`Project`](https://vedicreader.github.io/pullup/project.html#project) looks at the files in a folder, picks the flow that fits, and returns its steps. The folder here holds only a `pyproject.toml` with a `[tool.nbdev]` table, so it is an nbdev project:
+
+``` python
+project = Project(root)
+project.kind, [step.id for step in project.steps()]
+```
+
+    ('nbdev', ['prepare', 'bump', 'gh', 'pypi'])
+
+## Running the steps
+
+A [`Pipeline`](https://vedicreader.github.io/pullup/pipeline.html#pipeline) runs a list of steps for one project. Each step runs in a pseudo-terminal (PTY), so a program that asks for a password behaves as it would in your own shell, and every step’s output goes into one shared transcript. When a step passes, the next one starts by itself. When one fails, the pipeline stops there.
+
+`save` stores the plan and `start` launches the first step that has not yet passed. `start` returns as soon as the step is running, not when it finishes, which is why the transcript below shows the command but not yet its output. Call `state` or `tail` whenever you want to see how far it has got.
+
+``` python
+pipeline = Pipeline(root, dir='.demo')
+pipeline.save([{'id': 'hello', 'cmd': 'say hello',
+                'argv': [sys.executable, '-c', 'print("ready")']}])
+await pipeline.start()
+pipeline.state()['done'], pipeline.tail().splitlines()[-2:]
+```
+
+    (False, ['', '❯ say hello'])
+
+## Where plans are kept
+
+A saved plan is a JSON file inside the project folder, in the directory you pass as `dir` (`.pullup` unless you say otherwise). pullup never writes a plan outside the project:
+
+``` python
+custom = Pipeline(root, dir='.myapp')
+custom.save([{'id': 'show', 'cmd': 'show', 'argv': [sys.executable, '-c', 'print("saved")']}])
+custom.path.relative_to(root)
+```
+
+    Path('.myapp/pipeline.json')
+
+## Deploying a web app
+
+[`Deploy`](https://vedicreader.github.io/pullup/deploy.html#deploy) is a pipeline that puts a web app on a server. Its steps run the subcommands of a `deploy.py` script that lives in the project, and [`Deploy.scaffold`](https://vedicreader.github.io/pullup/deploy.html#deploy.scaffold) can write that script for you. [`Drive`](https://vedicreader.github.io/pullup/drive.html#drive) covers the same ground one library call at a time (write the Dockerfile, open the tunnel, provision the server), so you can run and check each part on its own. Both are pipelines, so they start, stop and report like the one above.
+
+``` python
+Deploy(root).state()['kind'], Drive(root).state()['kind']
+```
+
+    ('deploy', 'drive')
+
+## Workflows
+
+[`Workflows`](https://vedicreader.github.io/pullup/workflows.html#workflows) reads the GitHub Actions files in `.github/workflows` and turns each one into a row of triggers and jobs. Reading local files needs no GitHub token. Listing runs, starting them and pushing secrets do.
+
+``` python
+workflow_dir = root/'.github'/'workflows'
+workflow_dir.mkdir(parents=True)
+(workflow_dir/'ci.yml').write_text('''name: CI
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: pytest
+''')
+workflows = Workflows(root)
+[(row['name'], [job['id'] for job in row['jobs']]) for row in workflows.parsed()]
+```
+
+    [('CI', ['test'])]
+
+## Environment values
+
+Many steps need a token or a setting, such as `GITHUB_TOKEN` for a GitHub release. A step lists the names it needs under `needs`, and the pipeline looks them up in an environment store when it starts the step. The values are given to the child process only, and your own process environment is left alone. The default store is an [`EnvStore`](https://vedicreader.github.io/pullup/env.html#envstore), which keeps secrets in the system keychain, but any object with `get` and `values` methods will do, like the small one below:
+
+``` python
+class Values:
+    def get(self, key, secret=True): return 'demo-token' if key == 'DEMO_TOKEN' else ''
+    def values(self, keys): return {key: self.get(key) for key in keys if self.get(key)}
+
+with_values = Pipeline(root, env=Values(), dir='.env-demo')
+with_values.save([{'id': 'env', 'cmd': 'read environment', 'needs': ['DEMO_TOKEN'],
+                   'argv': [sys.executable, '-c', 'import os; print(os.environ["DEMO_TOKEN"])']}])
+await with_values.start()
+with_values.tail().splitlines()[-2:]
+```
+
+    ['', '❯ read environment']
+
+## Which package broke
+
+When a step fails with a Python traceback, the useful question is which of your own packages raised it. [`blame`](https://vedicreader.github.io/pullup/stack.html#blame) reads the traceback text, finds the deepest frame that belongs to one of the packages named in `family`, and returns that package with the file, the line, the function and the error message:
+
+``` python
+trace = '''Traceback (most recent call last):
+  File "/tmp/pullup/demo.py", line 7, in release
+    raise RuntimeError("stopped")
+RuntimeError: stopped
+'''
+blame(trace, family=['pullup'])
+```
+
+    {'package': 'pullup',
+     'file': '/tmp/pullup/demo.py',
+     'line': 7,
+     'fn': 'release',
+     'error': 'RuntimeError: stopped',
+     'open': '/tmp/pullup/demo.py',
+     'checkout': '',
+     'version': '0.0.4'}
+
+## Servers and tunnels
+
+[`Infra`](https://vedicreader.github.io/pullup/infra.html#infra) lists and deletes Hetzner servers and Cloudflare tunnels, and lists Cloudflare zones and DNS records, using the tokens in the project’s environment store. `status` says which of the two libraries are installed and which tokens are set, without sending a request. An empty `env` falls back to the default [`EnvStore`](https://vedicreader.github.io/pullup/env.html#envstore), so the answer below reflects the keychain of the machine that ran it:
+
+``` python
+infra = Infra(env={})
+infra.status()
+```
+
+    {'vpseasy': True,
+     'cfeasy': True,
+     'hcloud_token': True,
+     'cf_token': False,
+     'keys': ['HCLOUD_TOKEN', 'CLOUDFLARE_API_TOKEN']}

pullup-0.0.7/README.md

@@ -0,0 +1,141 @@
+# pullup
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+pullup is the engine behind a release and deploy panel. Point it at a project folder and it tells you what kind of project it is (an nbdev library, a plain Python package, a Rust crate and so on) and which commands release it. It then runs those commands in a terminal you can watch, and stops at the first one that fails. The same machinery runs the deploy of a web app to a virtual private server (VPS). pullup also reads the GitHub Actions workflows in the repository, writes new ones, and lists the Hetzner servers and Cloudflare tunnels the project uses.
+
+Every public call returns plain dictionaries and lists, so a user interface can draw them and a test can compare them. The work that talks to GitHub, Docker, Hetzner and Cloudflare is done by four sibling libraries: gheasy, dockeasy, vpseasy and cfeasy.
+
+## Install
+
+``` sh
+pip install pullup
+```
+
+This also installs gheasy, dockeasy, vpseasy and cfeasy. None of them is imported until a call needs it, so reading a project or running a release does not load them.
+
+## What kind of project is this
+
+A release flow is the ordered list of commands that publishes one kind of project. An nbdev library is released with `nbdev_prepare`, `nbdev_bump_version`, `nbdev_release_gh` and `nbdev_pypi`. A plain Python package and a Rust crate each have a different list. [`Project`](https://vedicreader.github.io/pullup/project.html#project) looks at the files in a folder, picks the flow that fits, and returns its steps. The folder here holds only a `pyproject.toml` with a `[tool.nbdev]` table, so it is an nbdev project:
+
+``` python
+project = Project(root)
+project.kind, [step.id for step in project.steps()]
+```
+
+    ('nbdev', ['prepare', 'bump', 'gh', 'pypi'])
+
+## Running the steps
+
+A [`Pipeline`](https://vedicreader.github.io/pullup/pipeline.html#pipeline) runs a list of steps for one project. Each step runs in a pseudo-terminal (PTY), so a program that asks for a password behaves as it would in your own shell, and every step’s output goes into one shared transcript. When a step passes, the next one starts by itself. When one fails, the pipeline stops there.
+
+`save` stores the plan and `start` launches the first step that has not yet passed. `start` returns as soon as the step is running, not when it finishes, which is why the transcript below shows the command but not yet its output. Call `state` or `tail` whenever you want to see how far it has got.
+
+``` python
+pipeline = Pipeline(root, dir='.demo')
+pipeline.save([{'id': 'hello', 'cmd': 'say hello',
+                'argv': [sys.executable, '-c', 'print("ready")']}])
+await pipeline.start()
+pipeline.state()['done'], pipeline.tail().splitlines()[-2:]
+```
+
+    (False, ['', '❯ say hello'])
+
+## Where plans are kept
+
+A saved plan is a JSON file inside the project folder, in the directory you pass as `dir` (`.pullup` unless you say otherwise). pullup never writes a plan outside the project:
+
+``` python
+custom = Pipeline(root, dir='.myapp')
+custom.save([{'id': 'show', 'cmd': 'show', 'argv': [sys.executable, '-c', 'print("saved")']}])
+custom.path.relative_to(root)
+```
+
+    Path('.myapp/pipeline.json')
+
+## Deploying a web app
+
+[`Deploy`](https://vedicreader.github.io/pullup/deploy.html#deploy) is a pipeline that puts a web app on a server. Its steps run the subcommands of a `deploy.py` script that lives in the project, and [`Deploy.scaffold`](https://vedicreader.github.io/pullup/deploy.html#deploy.scaffold) can write that script for you. [`Drive`](https://vedicreader.github.io/pullup/drive.html#drive) covers the same ground one library call at a time (write the Dockerfile, open the tunnel, provision the server), so you can run and check each part on its own. Both are pipelines, so they start, stop and report like the one above.
+
+``` python
+Deploy(root).state()['kind'], Drive(root).state()['kind']
+```
+
+    ('deploy', 'drive')
+
+## Workflows
+
+[`Workflows`](https://vedicreader.github.io/pullup/workflows.html#workflows) reads the GitHub Actions files in `.github/workflows` and turns each one into a row of triggers and jobs. Reading local files needs no GitHub token. Listing runs, starting them and pushing secrets do.
+
+``` python
+workflow_dir = root/'.github'/'workflows'
+workflow_dir.mkdir(parents=True)
+(workflow_dir/'ci.yml').write_text('''name: CI
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: pytest
+''')
+workflows = Workflows(root)
+[(row['name'], [job['id'] for job in row['jobs']]) for row in workflows.parsed()]
+```
+
+    [('CI', ['test'])]
+
+## Environment values
+
+Many steps need a token or a setting, such as `GITHUB_TOKEN` for a GitHub release. A step lists the names it needs under `needs`, and the pipeline looks them up in an environment store when it starts the step. The values are given to the child process only, and your own process environment is left alone. The default store is an [`EnvStore`](https://vedicreader.github.io/pullup/env.html#envstore), which keeps secrets in the system keychain, but any object with `get` and `values` methods will do, like the small one below:
+
+``` python
+class Values:
+    def get(self, key, secret=True): return 'demo-token' if key == 'DEMO_TOKEN' else ''
+    def values(self, keys): return {key: self.get(key) for key in keys if self.get(key)}
+
+with_values = Pipeline(root, env=Values(), dir='.env-demo')
+with_values.save([{'id': 'env', 'cmd': 'read environment', 'needs': ['DEMO_TOKEN'],
+                   'argv': [sys.executable, '-c', 'import os; print(os.environ["DEMO_TOKEN"])']}])
+await with_values.start()
+with_values.tail().splitlines()[-2:]
+```
+
+    ['', '❯ read environment']
+
+## Which package broke
+
+When a step fails with a Python traceback, the useful question is which of your own packages raised it. [`blame`](https://vedicreader.github.io/pullup/stack.html#blame) reads the traceback text, finds the deepest frame that belongs to one of the packages named in `family`, and returns that package with the file, the line, the function and the error message:
+
+``` python
+trace = '''Traceback (most recent call last):
+  File "/tmp/pullup/demo.py", line 7, in release
+    raise RuntimeError("stopped")
+RuntimeError: stopped
+'''
+blame(trace, family=['pullup'])
+```
+
+    {'package': 'pullup',
+     'file': '/tmp/pullup/demo.py',
+     'line': 7,
+     'fn': 'release',
+     'error': 'RuntimeError: stopped',
+     'open': '/tmp/pullup/demo.py',
+     'checkout': '',
+     'version': '0.0.4'}
+
+## Servers and tunnels
+
+[`Infra`](https://vedicreader.github.io/pullup/infra.html#infra) lists and deletes Hetzner servers and Cloudflare tunnels, and lists Cloudflare zones and DNS records, using the tokens in the project’s environment store. `status` says which of the two libraries are installed and which tokens are set, without sending a request. An empty `env` falls back to the default [`EnvStore`](https://vedicreader.github.io/pullup/env.html#envstore), so the answer below reflects the keychain of the machine that ran it:
+
+``` python
+infra = Infra(env={})
+infra.status()
+```
+
+    {'vpseasy': True,
+     'cfeasy': True,
+     'hcloud_token': True,
+     'cf_token': False,
+     'keys': ['HCLOUD_TOKEN', 'CLOUDFLARE_API_TOKEN']}

{pullup-0.0.6 → pullup-0.0.7}/pullup/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.0.6"
+__version__ = "0.0.7"
 
 # The names a caller reaches for. The modules stay importable for everything else.
 from .env import EnvError, EnvStore, venv_env

{pullup-0.0.6 → pullup-0.0.7}/pullup/deploy.py

@@ -29,11 +29,13 @@ DeployError = PipelineError
 _generator = 'Leela'
 
 def use_generator(name):
-    "Name the tool the generated `setup.py` and `deploy.py` say wrote them."
+    "Set the tool name that generated `setup.py` and `deploy.py` files say wrote them."
     global _generator
     _generator = str(name)
 
-def generator(): return _generator
+def generator():
+    "The tool name that generated scripts say wrote them."
+    return _generator
 
 # %% ../nbs/03_deploy.ipynb #dbcb05a3
 DEPLOY_KEYS = {
@@ -55,7 +57,7 @@ DEPLOY_STEPS = [
 
 # %% ../nbs/03_deploy.ipynb #d6728ee1
 def setup_template(app, domain, subdomain='', port=5001, lfs=True):
-    "lego's `setup.py`: the one-shot half of the pattern, with `ENV_KEYS` as its single source."
+    "The text of a one-time `setup.py` that prepares a project for deploying the lego way."
     host = f'{subdomain}.{domain}' if subdomain else domain
     patterns = "['*.png', '*.jpg', '*.jpeg', '*.webp', '*.ico', '*.mp3', '*.wav']"
     return f'''"""One-shot setup for {app}: gheasy schema, LFS, .env, the deploy workflow, secrets.
@@ -164,7 +166,7 @@ if __name__ == '__main__':
 
 # %% ../nbs/03_deploy.ipynb #695a8160
 def deploy_template(app, domain, subdomain='', port=5001, second_host=''):
-    "lego's `deploy.py` in full, with this project's names in it. `second_host` is lego's apex."
+    "The text of a `deploy.py` that builds, tunnels and deploys the app; `second_host` adds another hostname."
     host = f'{subdomain}.{domain}' if subdomain else domain
     tunnel = f'{subdomain or app}_{domain}'
     second = f'''
@@ -303,13 +305,13 @@ if __name__ == '__main__':
 
 # %% ../nbs/03_deploy.ipynb #d11ca8b9
 class Deploy(Pipeline):
-    "The deploy pipeline: the project's own `deploy.py`, one subcommand per step."
+    "The deploy pipeline, one step per subcommand of the project's `deploy.py`."
     FILE = DEPLOY_FILE
     KIND = 'deploy'
     @staticmethod
     def defaults(root): return list(DEPLOY_STEPS)
     def target(self):
-        "Where this deploy goes and what it is still missing, from the store the steps will read."
+        "Where this deploy goes, which secrets are still unset, and which generated files exist."
         store = self.env if isinstance(self.env, EnvStore) else EnvStore()
         def value(key, default=''): return env_value(store, key, default)
         missing = [k for k, v in DEPLOY_KEYS.items()
@@ -325,7 +327,7 @@ class Deploy(Pipeline):
             'keys': {k: (v is None) for k, v in DEPLOY_KEYS.items()}}
     def state(self): return super().state() | {'target': self.target()}
     def scaffold(self, domain='', subdomain='', app='', force=False, second_host=''):
-        "Write lego's pattern out: the one-shot `setup.py` and the `deploy.py` CI runs on every push."
+        "Write `deploy.py` and `setup.py`, record the deploy keys, add the deploy workflow, and return the paths written."
         domain = str(domain or '').strip()
         if not domain: raise DeployError('a domain is required — the host this app answers on')
         app = str(app or '').strip() or self.root.name

{pullup-0.0.6 → pullup-0.0.7}/pullup/drive.py

@@ -36,15 +36,15 @@ DriveError = PipelineError
 # %% ../nbs/04_drive.ipynb #3ab3ed04
 @dataclass
 class Part:
-    "One library call, as a step you can run on its own."
+    "One deploy operation as a code template that can run as a step on its own."
     id: str
-    package: str
+    package: str        # the library the code calls
     label: str
     doc: str
-    code: str
-    needs: list = field(default_factory=list)
-    writes: list = field(default_factory=list)
-    produces: list = field(default_factory=list)
+    code: str           # Python source whose `{placeholders}` are filled from `context`
+    needs: list = field(default_factory=list)      # keys the code reads
+    writes: list = field(default_factory=list)     # keys the code stores
+    produces: list = field(default_factory=list)   # files the code creates
 
 # %% ../nbs/04_drive.ipynb #b80f6bff
 PARTS = [
@@ -111,7 +111,7 @@ PARTS = [
 
 # %% ../nbs/04_drive.ipynb #0cd71f13
 def context(root, env=None):
-    "The values every snippet is rendered with, resolved once."
+    "The project values every part's template is filled with: names, host, tunnel, port and file lists."
     root = Path(root).expanduser().resolve()
     store = env or EnvStore()
     def value(key, default=''): return env_value(store, key, default)
@@ -151,13 +151,13 @@ def _step(part, exe, ctx):
 
 # %% ../nbs/04_drive.ipynb #b532d107
 def parts(root, env=None, python=''):
-    "Every part as a runnable step, with this project's values already in the snippet."
+    "Every part as a runnable `Step`, its template filled with this project's values."
     ctx = context(root, env)
     return [_step(p, str(python or sys.executable), ctx) for p in PARTS]
 
 # %% ../nbs/04_drive.ipynb #bc95dca4
 class Drive(Pipeline):
-    "The deploy, driven a library at a time."
+    "The deploy as six separate library calls, each a step you can run on its own."
     FILE = DRIVE_FILE
     KIND = 'drive'
     def __init__(self, root, python=None, env=None, dir=DIR):
@@ -166,7 +166,7 @@ class Drive(Pipeline):
     @staticmethod
     def defaults(root): return parts(root)
     def refresh(self):
-        "Re-render the snippets against the current values."
+        "Render the parts again if the store's values changed, unless a plan has been saved."
         if self.path.exists(): return self.steps
         key = json.dumps(context(self.root, self.env), sort_keys=True)
         if key != self._rendered:

{pullup-0.0.6 → pullup-0.0.7}/pullup/env.py

@@ -16,19 +16,19 @@ class EnvError(RuntimeError): pass
 
 # %% ../nbs/00_env.ipynb #9d27ac2f
 def strip_bundle(env, frozen=None):
-    "Return `env` without frozen-host interpreter redirection."
+    "Remove the frozen-app interpreter variables from `env` when running frozen, and return it."
     if not (getattr(sys, 'frozen', False) if frozen is None else frozen): return env
     for name in BUNDLE_ONLY: env.pop(name, None)
     env['PYTHONUTF8'] = '1'
     return env
 
 def clean_env():
-    "Return this process's environment without bundle variables."
+    "A copy of this process's environment with the frozen-app interpreter variables removed."
     return strip_bundle(os.environ.copy(), frozen=True)
 
 # %% ../nbs/00_env.ipynb #4b56c811
 def venv_env(python=None, env=None):
-    "Return `env` with `python`'s virtual environment prepended to `PATH`; None leaves the environment unchanged."
+    "A copy of `env` that runs commands in the virtual environment of `python`, or unchanged when `python` is None."
     env = strip_bundle(dict(os.environ if env is None else env))
     if not python: return env
     bindir = str(Path(python).parent)
@@ -42,13 +42,17 @@ def venv_env(python=None, env=None):
 _extra = 'pullup'
 
 def use_extra(name):
-    "Name the package every message about the cloud half tells the reader to install."
+    "Set the package name that missing-library errors tell the reader to install."
     global _extra
     _extra = str(name)
 
-def extra(): return _extra
+def extra():
+    "The package name that missing-library errors tell the reader to install."
+    return _extra
 
-def needs_extra(what): return f'{what}: pip install "{_extra}"'
+def needs_extra(what):
+    "An error message for `what` that ends with the command that installs the missing library."
+    return f'{what}: pip install "{_extra}"'
 
 # %% ../nbs/00_env.ipynb #e34073db
 def _dockeasy():
@@ -76,16 +80,16 @@ def _call(fn, *args, **kwargs):
 
 # %% ../nbs/00_env.ipynb #9937a32a
 class EnvStore:
-    "The environment keys one project cares about, read and written through dockeasy."
+    "Read and write one project's tokens and settings through dockeasy's keychain and env file."
     def __init__(self, service='fastops', path=None): self.service, self.path = service, path
     def get(self, key, secret=True):
-        "One value, from the keychain or the env file, falling back to this process's environment."
+        "One value from the keychain, the environment or the env file, or `''` when none has it."
         env_get, _set, secret_get, _sset = _dockeasy()
         stored = (_call(secret_get, key, service=self.service, path=self.path) if secret
                   else _call(env_get, key, path=self.path))
         return stored or os.environ.get(key) or ''
     def set(self, key, value, secret=True):
-        "Store one value. A secret goes to the keychain as well as the file; a variable does not."
+        "Store one value: a secret in the keychain and the env file, anything else in the env file only."
         key = str(key or '').strip()
         if not key: raise EnvError('a key is required')
         if not str(value): raise EnvError(f'{key} needs a value')
@@ -94,7 +98,7 @@ class EnvStore:
         else: _call(env_set, key, str(value), path=self.path)
         return {'key': key, 'secret': bool(secret)}
     def unset(self, key):
-        "Remove a value from every place `set` put it. Says which places actually held one."
+        "Remove a value from the keychain, the env file and `os.environ`, and say which of the first two held it."
         from dockeasy.core import _FASTOPS_ENV
         from dotenv import unset_key
         key, gone = str(key), []
@@ -112,7 +116,7 @@ class EnvStore:
         os.environ.pop(key, None)
         return {'key': key, 'removed': gone}
     def values(self, keys, secret=True):
-        "Every key that has a value, as a dict. A key with none is absent rather than empty."
+        "The keys that have a value, as a dict; keys with no value are left out."
         out = {}
         for k in keys:
             try: v = self.get(k, secret=secret)
@@ -122,6 +126,6 @@ class EnvStore:
 
 # %% ../nbs/00_env.ipynb #55636ab5
 def env_value(store, key, default='', secret=False):
-    "One value out of an environment store, or `default` when it is unset or unreadable."
+    "One value from an environment store, or `default` when it is unset or the store raises."
     try: return store.get(key, secret=secret) or default
     except Exception: return default

{pullup-0.0.6 → pullup-0.0.7}/pullup/infra.py

@@ -50,14 +50,16 @@ def _why(what, pkg, e):
 
 # %% ../nbs/08_infra.ipynb #f5433bf9
 class Infra:
-    "Hetzner and Cloudflare, through vpseasy and cfeasy, with this project's tokens."
+    "Hetzner servers and Cloudflare tunnels, zones and DNS records, using this project's tokens."
     HCLOUD, CF_TOKEN = 'HCLOUD_TOKEN', 'CLOUDFLARE_API_TOKEN'
     def __init__(self, env=None):
         self.env = env or EnvStore()
     def token(self, key):
+        "A token from the store, else from this process's environment, else `''`."
         try: return self.env.get(key) or os.environ.get(key, '')
         except Exception: return os.environ.get(key, '')
     def status(self):
+        "Which libraries are installed and which tokens are set, without the values."
         return {'vpseasy': installed('vpseasy'), 'cfeasy': installed('cfeasy'),
                 'hcloud_token': bool(self.token(self.HCLOUD)),
                 'cf_token': bool(self.token(self.CF_TOKEN)),
@@ -78,27 +80,31 @@ class Infra:
         "Every Hetzner server on this token, as vpseasy reports them."
         return list(self._hetzner().servers())
     def delete_server(self, name):
-        "Delete one server, named. Irreversible, and the caller is expected to have asked."
+        "Delete one server by name; this cannot be undone, so ask the user first."
         name = str(name or '').strip()
         if not name: raise InfraError('name the server to delete')
         known = {s['name'] for s in self.servers()}
         if name not in known: raise InfraError(f'no server called {name}')
         self._hetzner().delete(name)
         return {'deleted': name}
-    def keys(self): return list(self._hetzner().keys())
+    def keys(self):
+        "The SSH keys on the Hetzner account."
+        return list(self._hetzner().keys())
     def tunnels(self):
-        "Live Cloudflare tunnels, trimmed to what a panel can show."
+        "Cloudflare tunnels that have not been deleted, with their status and connection count."
         rows = [{'id': t.get('id') or '', 'name': t.get('name') or '',
                  'status': t.get('status') or '', 'created_at': str(t.get('created_at') or ''),
                  'deleted_at': str(t.get('deleted_at') or ''),
                  'connections': len(t.get('connections') or [])} for t in self._cf().tunnels()]
         return [r for r in rows if not r['deleted_at']]
     def delete_tunnel(self, tunnel_id):
+        "Delete one Cloudflare tunnel by id."
         tunnel_id = str(tunnel_id or '').strip()
         if not tunnel_id: raise InfraError('name the tunnel to delete')
         self._cf().delete_tunnel(tunnel_id)
         return {'deleted': tunnel_id}
     def zones(self):
+        "The Cloudflare zones this token can see."
         return [{'id': z.get('id') or '', 'name': z.get('name') or '', 'status': z.get('status') or ''}
                 for z in self._cf().zones()]
     def records(self, zone):
@@ -109,10 +115,10 @@ class Infra:
         zid = zone if len(zone) == 32 and '.' not in zone else cf.zone_id(zone)
         return sorted((_record(r) for r in cf.dns_records(zid)), key=lambda r: (r['name'], r['type']))
     def verify(self):
-        "cfeasy's own token check, so a permissions problem is named before a deploy hits it."
+        "Run cfeasy's token check, so a missing permission shows up before a deploy."
         return self._cf().verify()
     def overview(self):
-        "Everything at once as `{rows, error}` each, so Cloudflare being down cannot hide the servers."
+        "Servers, tunnels and zones as `{rows, error}` each, so one failing provider cannot hide the others."
         out = {'status': self.status()}
         for key, fn in (('servers', self.servers), ('tunnels', self.tunnels), ('zones', self.zones)):
             try: out[key] = {'rows': fn(), 'error': ''}