pykern.pkcli package

Invoke commands from command line interpreter modules.

Any module in <root_pkg>.pkcli will be found by this module. The public functions of the module will be executed when called from the command line. This module is invoked by pykern.pykern_console. Every project must have its own invocation module.

The basic form is: <project> <simple-module> <function>. <simple-module> is the module without <root_pkg>.pkcli. <function> is any function that begins with a letter and contains word characters.

If the module only has one public function named default_command, the form is: <project> <simple-module>.

The purpose of this module is to simplify command-line modules. There is no boilerplate. You just create a module with public functions in a particular package location (e.g. pykern.pkcli). This module does the rest.

pykern.pkcli.pkexample is a working example.

copyright:

Copyright (c) 2015-2023 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.CLI_PKG = ['pkcli']

Sub-package to find command line interpreter (cli) modules will be found

exception pykern.pkcli.CommandError

Bases: Exception

argh.CommandError is caught by argh, and does not cause an exit

This CommandError causes an exit(1).

class pykern.pkcli.CustomFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: CustomFormatter

class pykern.pkcli.CustomParser(*args, **kwargs)

Bases: ArghParser

format_help()

print_help()

pykern.pkcli.DEFAULT_COMMAND = 'default_command'

If a module only has one command named this, then execute directly.

pykern.pkcli.command_error(fmt, *args, **kwargs)

Raise CommandError with msg

Parameters:

fmt (str) – how to represent arguments

Raises:

CommandError – always

pykern.pkcli.command_info(fmt, *args, **kwargs)

Write message to stderr without raising

Parameters:

fmt (str) – how to represent arguments

pykern.pkcli.main(root_pkg, argv=None)

Invokes module functions in pykern.pkcli

Looks in <root_pkg>.pkcli for the argv[1] module. It then invokes the argv[2] method of that module.

Parameters:

• root_pkg (str) – top level package name

• argv (list of str) – Defaults to sys.argv. Only used for testing.

Returns:

0 if ok. 1 if error (missing command, etc.)

Return type:

int

Submodules

pykern.pkcli.ci module

Continuous integration (CI) support

To execute all checks and tests in a CI script, use:

pykern ci run

copyright:

Copyright (c) 2022 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.ci.check_eof_newline()

Recursively check repo for files missing newline at end of file.

Checks html, jinja, js, json, md, py, tsx, and yml files. Excludes external files, tests, and run directory.

pykern.pkcli.ci.check_main()

Recursively check repo for modules with main programs.

Checks .py files. Excludes <project>_console.py, tests, and venv.

pykern.pkcli.ci.check_prints()

Recursively check repo for (naked) print and pkdp calls.

Checks .py files, excluding hidden files, pkdebug module, test data/work, run directory, package_data and venv.

See the DesignHints <https://github.com/radiasoft/pykern/wiki/DesignHints#output-for-programmers-logging>_ wiki for an explanation of why this check is necessary.

If you really need a print, use pykern.pkconst.builtin_print.

pykern.pkcli.ci.run()

Run the continuous integration checks and tests:

1. Runs check_prints

2. Checks formatting

3. Runs pykern.pkcli.test.default_command

pykern.pkcli.fmt module

Wrapper for Python formatter (currently, black) to update and to validate a repository.

copyright:

Copyright (c) 2022 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.fmt.check(*paths)

Returns True if there would be diff else return False

Parameters:

*paths (strs or py.paths) – strings or py.paths to file or directory

pykern.pkcli.fmt.diff(*paths)

Run diff on file comparing formatted vs. current file state

Parameters:

*paths (strs or py.paths) – strings or py.paths to file or directory

pykern.pkcli.fmt.run(*paths)

Run black formatter on path

Parameters:

*paths (strs or py.paths) – strings or py.paths to file or directory

pykern.pkcli.github module

run github backups and restores

copyright:

Copyright (c) 2013-2018 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

class pykern.pkcli.github.GitHub

Bases: object

classmethod indent2(text)

classmethod issue_body(issue)

list_org_repos(org, include_forks)

Returns list of repos for org

login()

milestone(repo, title)

repo(repo)

repo_arg(repo)

pykern.pkcli.github.backup(org)

Backs up all github repos in org into pwd

Parameters:

org (str) – backup all repos visible to user

Creates timestamped directory, and purges directories older than cfg.keep_days

Note: backups are incremental in case of repositories to save space. Hard-linking is used between “keep_dates”. The assumption here is that the github backup is actually copied to a backup server.

pykern.pkcli.github.ci_check(repo, branch=None)

pykern.pkcli.github.collaborators(org, filename, affiliation='outside', private=True)

Lists direct repos to which user has access and is not a team member

Configured user must be an owner

Parameters:

• org (str) – GitHub organization

• affiliation (str) – all, direct, outside

pykern.pkcli.github.create_issue(repo, title, body='', assignees=None, labels=None, milestone=None)

pykern.pkcli.github.create_milestone(repo, title, description='', due_on=None)

pykern.pkcli.github.get_milestone(repo, title)

pykern.pkcli.github.issue_pending_alpha(repo)

Create “Alpha Release [pending]” issue

This should be created after the current alpha completes.

pykern.pkcli.github.issue_start_alpha(repo)

pykern.pkcli.github.issue_start_beta(repo)

pykern.pkcli.github.issue_start_prod(repo, from_alpha=False)

pykern.pkcli.github.issue_update_alpha_pending(repo)

pykern.pkcli.github.issues_as_csv(repo)

Export issues as CSV

Parameters:

repo (str) – will add radiasoft/ if missing

pykern.pkcli.github.labels(repo, clear=False)

Setup the RadiaSoft labels for repo.

Will add “radiasoft/” to the name if it is missing.

Parameters:

• repo (str) – will add https://github.com/radiasoft if missing

• clear (bool) – if True, clear all existing labels

pykern.pkcli.github.list_repos(org, include_forks=False)

Lists repos for org, possibly including forks

Parameters:

• org (str) – GitHub organization

• include_forks (bool) – include forks or not

pykern.pkcli.github.restore(git_txz)

Restores the git directory (only) to a new directory with the .git.txz suffix

pykern.pkcli.github_orgmode module

convert to/from orgmode

copyright:

Copyright (c) 2022 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.github_orgmode.assignee_issues(user, org_d='~/org')

Export issues for auth user to orgmode file named org_d/user.org

Parameters:

• user (str) – user name to use

• org_d (str) – where to store org files [~/org]

Returns:

Name of org file created

Return type:

str

pykern.pkcli.github_orgmode.from_issues(*repos, org_d='~/org')

Export issues to orgmode file named org_d/repo.org

Parameters:

• repos (str) – will add radiasoft/ if missing

• org_d (str) – where to store org files [~/org]

Returns:

Name of org file created

Return type:

str

pykern.pkcli.github_orgmode.test_data(repo, path)

Used to generate the unit test data

pykern.pkcli.github_orgmode.to_issues(org_path, dry_run=False)

Import (existing) issues from org_d/repo.org

Parameters:

• org_path (str) – org mode file

• dry_run (bool) – whether to update issues or not

Returns:

updates made

Return type:

str

pykern.pkcli.pkexample module

Demonstrate how to write reusable command line tools.

A pykern.pkcli module is designed to be used from any context any other piece of code. Since we use argh, it makes it easy to dispatch with a bit of glue so that all you have to do is write a function.

Documentation should be provided as a normal docstring for the function. See echo.

You should set up your project directory with pykern.pkcli.projex, which will give you a shell command that gets automatically installed. Each project has one such command. For example, pykern.pykern_console is the module that invokes all pykern pkcli functions.

To invoke echo, use the shell command:

$ pykern pkexample echo something
howdy: something

The output of the function is printed on stdout so if you don’t have to print messages, and the function can be used in other contexts where stdout is not useful (e.g. returned to a brower).

If you invoke this module without arguments, you get a list of functions you can call:

$ pykern pkexample usage: pykern pkexample [-h] {echo,primes} … pykern pkexample: error: too few arguments

This list only includes “public” functions (not beginning with an underscore).

In your project, you’ll have your own function, for example, you can start Sirepo with:

$ sirepo service http
 * Running on http://0.0.0.0:8000/
 * Restarting with reloader

The module sirepo.sirepo_console is automatically installed as a shell command by setup.py, and pykern.pkcli searches for modules to invoke in the package sirepo.pkcli. In fact, you can list out all modules by invoking sirepo without any arguments:

$ sirepo
usage: sirepo module command [args...]
Modules:
celery
elegant
service
srw
warp

copyright:

Copyright (c) 2016 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.pkexample.echo(suffix, prefix='howdy: ')

Concatenate prefix and suffix

Parameters:

• to_echo (str) – what to print and must be at least five chars

• prefix (str) – what to put in front of to_echo [“howdy: “]

Returns:

prefix + suffix

Return type:

str

pykern.pkcli.projex module

Initialize Python project directories

copyright:

Copyright (c) 2015 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.projex.DEFAULTS = {'copyright_license_rst': ':copyright: Copyright (c) {year} {author}.  All Rights Reserved.\n:license: {license}', 'license': 'apache2', 'year': 2026}

Default values

pykern.pkcli.projex.LICENSES = {'agpl3': ('https://www.gnu.org/licenses/agpl-3.0.txt', 'License :: OSI Approved :: GNU Affero General Public License v3'), 'apache2': ('https://www.apache.org/licenses/LICENSE-2.0.html', 'License :: OSI Approved :: Apache Software License'), 'gpl2': ('https://www.gnu.org/licenses/gpl-2.0.txt', 'License :: OSI Approved :: GNU General Public License v2 (GPLv2)'), 'gpl3': ('https://www.gnu.org/licenses/gpl-3.0.txt', 'License :: OSI Approved :: GNU General Public License v3 (GPLv3)'), 'lgpl2': ('https://www.gnu.org/licenses/lgpl-2.0.txt', 'License :: OSI Approved :: GNU Lesser General Public License v2 (LGPLv2)'), 'lgpl3': ('https://www.gnu.org/licenses/lgpl-3.0.txt', 'License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)'), 'mit': ('https://opensource.org/licenses/MIT', 'License :: OSI Approved :: MIT License'), 'proprietary': ('PROPRIETARY AND CONFIDENTIAL. See LICENSE file for details.', 'License :: Other/Proprietary License')}

Licenses

pykern.pkcli.projex.init_rs_tree(description)

Initialize defaults for RadiaSoft project tree and call init_tree

description is passed verbatim. Other args passed to init_tree:

name

Base name of the current directory

author

“RadiaSoft LLC”

author_email

“pip@radiasoft.net”

license

“apache2”

url

“https://git.radiasoft.org/{name}”

Parameters:

description (str) – one-line summary of project

pykern.pkcli.projex.init_tree(name, author, author_email, description, license, url, overwrite=False)

Setup a project tree with: docs, tests, etc., and checkin to git.

Creates: pyproject.toml, index.rst, project dir, <name>_console.py, etc. Overwrites files if they exist without checking.

Parameters:

• name (str) – short name of the project, e.g. pykern.

• author (str) – copyright holder, e.g. RadiaSoft LLC

• author_email (str) – how to reach author, e.g. pip@pykern.org

• description (str) – one-line summary of project

• license (str) – name of license, e.g. apache2, mit, and proprietary.

• url (str) – website for project, e.g. https://pykern.org

• overwrite (bool) – overwrite existing files [False]

pykern.pkcli.projex.upgrade_tree()

Upgrade from setup.py to pyproject.toml

Replaces all generated files.

pykern.pkcli.rsmanifest module

Create and read global and user manifests.

copyright:

Copyright (c) 2017 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.rsmanifest.BASENAME = 'rsmanifest.json'

Appears in each directory

pykern.pkcli.rsmanifest.CONTAINER_FILE = '/rsmanifest.json'

Written once at build time

pykern.pkcli.rsmanifest.FILE_VERSION = '20170217.180000'

Format version

pykern.pkcli.rsmanifest.USER_FILE = '~/rsmanifest.json'

Read and written multiple times as the run user

pykern.pkcli.rsmanifest.add_code(name, version, uri, source_d, virtual_env=None, pyenv=None)

Add a new code to ~?rsmanifest.json

Parameters:

• name (str) – name of the package

• version (str) – commit or version

• uri (str) – repo, source link

• source_d (str) – directory containing

• virtual_env (str) – DEPRECATED

• pyenv (str) – pyenv version

pykern.pkcli.rsmanifest.pkunit_setup()

Create rsmanifest files

pykern.pkcli.rsmanifest.read_all()

Merge all manifests

Returns:

merged data

Return type:

dict

pykern.pkcli.sim module

wrapper for running simulations

copyright:

Copyright (c) 2017 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.sim.cfg = None

configuration

pykern.pkcli.sim.default_command(cmd, *args, **kwargs)

Wrapper until figure out args with argh

pykern.pkcli.sphinx module

Generate documentation with Sphinx

copyright:

Copyright (c) 2024 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.sphinx.build(builder='html')

prepare and run sphinx-build for html

Reads pyproject.toml to get project name. Creates _build_<builder> subdirectory with the output.

Parameters:

builder (str) – types of builders. See Sphinx builder list [html]

pykern.pkcli.sphinx.prepare(package)

Create conf.py and run sphinx-apidoc

conf.py is generated from package metadata so package must be installed.

Parameters:

package (str) – package to build

pykern.pkcli.test module

run test files in separate processes

copyright:

Copyright (c) 2019 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.test.default_command(*args)

Run tests one at a time with py.test.

Searches in tests sub-directory if not provided a list of tests or not in tests/ already

Arguments are directories or files, which are searched for _test.py files.

An argument which is case=<pattern>, is passed to pytest as -k <pattern>. An argument of the form <file>::<case> runs that specific test by node ID. These two forms are mutually exclusive.

skip_past=<last_to_ignore> causes collection to ignore all files up to and including <last_to_ignore>` (may be partial match of the test file).

max_procs=2 starts two cases simultaneously. Default is 1, or config value PYKERN_PKCLI_TEST_MAX_PROCS if set.

Writes failures to <base>_test.log

Parameters:

args (str) – test dirs, files, options

Returns:

passed=N if all passed, else raises pkcli.Error

Return type:

str

pykern.pkcli.web module

mirror a website as a static site

copyright:

Copyright (c) 2026 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

pykern.pkcli.web.mirror(url, output_dir, rules_file=None)

Mirror url as a static site in output_dir

Fetches pages starting from url, follows internal links within the same URL prefix, rewrites URLs to relative, and strips analytics. Contact pages are replaced with mailto links.

Parameters:

• url (str) – starting URL to mirror

• output_dir (str) – local directory for output files

• rules_file (str) – optional path to a YAML rules file

pykern.pkcli.xlsx module

manipulate Excel spreadsheets

copyright:

Copyright (c) 2025 RadiaSoft LLC. All Rights Reserved.

license:

http://www.apache.org/licenses/LICENSE-2.0.html

class pykern.pkcli.xlsx.ToCSV(xlsx_path, sheet, csv_path)

Bases: object

pykern.pkcli.xlsx.to_csv(xlsx_path, sheet=None, csv_path=None)

Dump sheets from xlsx_path

Parameters:

• xlsx_path (str or py.path) – what to parse

• sheet (str or int) – dump a specfic sheet [None: all]

• csv_path (str or py.path) – where to write [base#N.csv]

Returns:

list of csv files created

Return type:

tuple