pullup 0.0.6__tar.gz → 0.0.8__tar.gz

pullup-0.0.8/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: pullup
+Version: 0.0.8
+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.8/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.8}/pullup/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.0.6"
+__version__ = "0.0.8"
 
 # 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.8}/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.
@@ -86,8 +88,8 @@ def _load_env():
     return dict(os.environ) | (parse_env(fn=str(envf)) if envf.exists() else {{}})
 
 def env2push():
-    'Schema defaults overlaid with whatever is actually set locally.'
-    return ENV_KEYS | filter_keys(_load_env(), in_(ENV_KEYS))
+    'Schema defaults overlaid with the local values, leaving out keys with no value so GitHub never stores "None".'
+    return {{k: v for k, v in (ENV_KEYS | filter_keys(_load_env(), in_(ENV_KEYS))).items() if v not in (None, 'None', '')}}
 
 def init_gheasy():
     cfg = GheasyConfig.load(ROOT)
@@ -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'''
@@ -179,13 +181,14 @@ runs whatever this file says.
     python deploy.py compose
     python deploy.py deploy
     python deploy.py status
-    python deploy.py nuke
+    python deploy.py rollback [tag]
+    python deploy.py nuke [--tunnel]
 """
 import os, sys, secrets
 from fastcore.all import Path
 from dockeasy import detect_app, env_set, env_get
 from cfeasy import CF
-from vpseasy import caddy_stack, hetzner_deploy, Hetzner
+from vpseasy import caddy_stack, hetzner_deploy, Hetzner, wait_http, rollback as vps_rollback
 
 root = Path(__file__).resolve().parent
 app, domain, subdomain = {app!r}, {domain!r}, {subdomain!r}
@@ -267,6 +270,22 @@ def deploy(force=None):
     env_set('HETZNER_IP', r.ip, path=root/'.env')
     if r.key: env_set('HETZNER_KEY', r.key, path=root/'.env')
     print(f'deployed: https://{{host}} at {{r.ip}}')
+    after_deploy(cf)
+
+def after_deploy(cf):
+    \'\'\'Wait until the site answers, then purge Cloudflare's cache for the host so visitors get the new pages.
+    vpseasy's deploy already keeps the replaced image for `rollback` and prunes dangling images.
+    Empty this function to skip both steps.\'\'\'
+    if not wait_http(f'https://{{host}}/', ua=f'{{app}}-deploy', tries=20): return print('site not answering yet; cache not purged')
+    try: cf.purge(cf.zone_id(domain), prefixes=[f'{{host}}/'], fallback_all=False); print('cache purged:', host)
+    except Exception as e: print(f'cache not purged: {{e}}')
+
+def rollback(to=None):
+    "Run the image before the last deploy, or the kept image tagged `to`."
+    ip = env_get('HETZNER_IP', path=root/'.env')
+    if not ip: return print('no server yet')
+    vps_rollback(ip, to, path=srv, user=env_get('SERVER_USER', path=root/'.env', default='deploy'),
+                 key=env_get('HETZNER_KEY', path=root/'.env', default=None))
 
 def status():
     "Which servers exist on this token, and which tunnels."
@@ -276,14 +295,17 @@ def status():
     for t in cf.tunnels(): print(f'tunnel {{t.get("name","")!r:22}} {{t.get("id","")}}')
     print(f'this project deploys as {{name}} -> {{host}}')
 
-def nuke():
-    "Delete the server and the tunnel. Irreversible, so it asks for a token you have to read."
+def nuke(tunnel=False):
+    \'\'\'Delete the server, and with `tunnel` the tunnel too. Irreversible, so it asks for a token you have to read.
+    The tunnel serves the site from whichever box runs its connector, so after a move to a new server keep it.\'\'\'
     typ = secrets.token_urlsafe(8)
-    if input(f'This deletes the server and the tunnel. Type {{typ}} to proceed: ') != typ:
+    what = 'the server and the tunnel' if tunnel else 'the server'
+    if input(f'This deletes {{what}}. Type {{typ}} to proceed: ') != typ:
         return print('aborted')
     name = env_get('SERVER_NAME', path=root/'.env', default=app)
     Hetzner().delete(name)
     print(f'server {{name}} deleted')
+    if not tunnel: return print('tunnel kept (python deploy.py nuke --tunnel deletes it)')
     try:
         cf = CF(token=env_get('CLOUDFLARE_API_TOKEN', path=root/'.env'))
         cf.delete_tunnel(cf.tunnel_id(tunnel_name))
@@ -297,23 +319,24 @@ if __name__ == '__main__':
     elif cmd == 'env': mk_env()
     elif cmd == 'deploy': deploy(force=args[1] if len(args) > 1 else None)
     elif cmd == 'status': status()
-    elif cmd == 'nuke': nuke()
-    else: print('usage: deploy.py env | compose | deploy | status | nuke')
+    elif cmd == 'rollback': rollback(args[1] if len(args) > 1 else None)
+    elif cmd == 'nuke': nuke(tunnel='--tunnel' in args)
+    else: print('usage: deploy.py env | compose | deploy | status | rollback [tag] | nuke [--tunnel]')
 '''
 
 # %% ../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)
+        def value(key, default=''): return env_value(store, key) or env_value(store, key.lower(), default)
         missing = [k for k, v in DEPLOY_KEYS.items()
-                   if v is None and not env_value(store, k, secret=True)]
+                   if v is None and not (env_value(store, k, secret=True) or env_value(store, k.lower(), secret=True))]
         return {'app': value('APP') or self.root.name, 'domain': value('DOMAIN'),
             'server': value('SERVER_NAME'), 'user': value('SERVER_USER', 'deploy'),
             'port': value('PORT', '5001'), 'missing': missing,
@@ -325,7 +348,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.8}/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.8}/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