Package: pib-cli
PIB CLIA batteries includedmakestyle CLI forpythonprojects ingitrepositories.Project DocumentationMaster BranchProduction BranchDocumentation BuildsSupported Python VersionsTested to work with the following Python versions:Python 3.7Python 3.8Python 3.9Python 3.10InstallationTo install, simply use:pip install pib_clipip install pib_cli[docs](AddsSphinxsupport.)pip install pib_cli[docstrings](Addspydocstylesupport.)pip install pib_cli[types](Addsmypysupport.)UsageThe CLI itself is launched with thedevcommand.Trydev --helpfor details.With Cookiecutterpib_cliis also baked into thisCookie Cuttertemplate:Python In A BoxLicenseMPL-2Included PackagesAs it's batteries included,pib_cliships with a slightly opinionated list of popular development packages.  You can customize the exact mix by specifying one or moreextraswhen installing the package.Core installed packagespackageDescriptionbanditFinds common security issuescommitizenStandardizes commit messagesisortSorts importspre-commitPre-commit hook managerpylintStatic code analysispytestTesting with Pythonpytest-covCoverage support for pytestpytest-pylintPylint support for pytestsafetyDependency vulnerability scanningwheelPackage distribution toolsyamllintLint YAML configuration filesyapfCustomizable code formattingInstalled and required by pib_clipackageDescriptionclickCommand line interface toolkitjsonschemaJSON Schema validation for PythonGitPythonInteract with Git repositoriesPyYAMLYAML parser and emitter for Pythonpip install pib_clito install only these dependencies.These become indirectdevelopmentdependencies ofYOURproject, so it's good to keep that in mind.'docs' extraspackageDescriptiondarglintSphinx style guide enforcementsphinxPython documentation generatorsphinx-autopackagesummaryTemplate nested module contentsphinx_rtd_themeTheRead the DocsSphinx themepip install pib_cli[docs]to add these dependencies to the core installation.'docstrings' extraspackageDescriptionpydocstylePEP 257 enforcementpip install[docstrings]to add these dependencies to the core installation.'types' extraspackageDescriptionmypyStatic type checkerpip install pib_cli[types]to add these dependencies to the core installation.'pib_docs' extraspackageDescriptionsphinxPython documentation generatorsphinx-autopackagesummaryTemplates nested module contentsphinx-clickGenerates CLI documentationsphinx-intlGenerates documentation translationssphinx-jsonschemaGenerates JSON schema documentationsphinx_rtd_themeTheRead the DocsSphinx themepip install pib_cli[pib_docs]to add these dependencies to the core installation.These extras exist only to support buildingpib_clidocumentation- they aren't meant to be consumed by user projects.Installing multiple extrasThis is straightforward to do:pip install pib_cli[docs,docstrings,types]Customizing the Command Line InterfaceThe most powerful feature ofpib_cliis its ability to customize how it interacts with the packages it brings to your project.  In this way it's very similar to the standard Linuxmakecommand- with the notable difference being thatpib_cliis packaged with a suite of Python libraries.The CLI configuration file is in YAML format, and conforms tothisset of JSON schemas.pib_cli v1.0.0 introduces anew JSON schema version.pib_cli v1.2.0 introducesfurther refinements to the JSON schemabut is fully backwards compatible with v1.0.0, andALLlegacy configuration files.Creating a '.pib.yml' fileThe.pib.ymlfile is where you can take control, and customizepib_clibehaviour to suit your particular needs.  This file should adhere to the specification detailed above- read on for further detail.The top level of your.pib.ymlfile should include metadata information.  This metadata is used to tellpib_cliwhere to find your project's codebase and any documentation (Sphinx) definitions.metadata:project_name:"Tellpib_clithefolderyourcodebaseisin."documentation_root:"Tellpib_cliwheretofindyourdocumentationdefinitions."cli_definition:-[A YAML array of cli command definitions,which are detailed in the next section].Thecli_definitionsection is mandatory, andpib_cliwill throw an error if it's missing.The metadata itself though is actually optional, and can also be declared using environment variables.Understanding pib_cli metadataMetadata tellspib_cliwhere to find your project's files, so it's important to set these values appropriately:project_nameis your project's name from a Python perspective.  It's the top level folder (inside your git repository) that houses your codebase, such thatfrom <project_name> import *would be accessing your codebase.documentation_rootis a relative path from your repository's root to a folder containing a Sphinx Makefile.  This is purely a convenience definition for any documentation related commands.Environment variables and pib_cliYou may also define your project's metadata by setting environment variables.  This would allow you to reuse the same CLI configuration for multiple projects:project_namecan also be defined byPIB_PROJECT_NAMEenvironment variabledocumentation_rootcan also be defined by thePIB_DOCUMENTATION_ROOTenvironment variableWhen configuration AND environment variables exist,pib_cliwillprefer to use environment variable values.Environment variables and pib_cli commandsRegardless of whether you have used configuration or environment variables, when your CLI commands are executed, the environment variables will be available in the shell:PIB_PROJECT_NAMEwill always be defined and accessible from inside the shellPIB_DOCUMENTATION_ROOTwill always be defined and accessible from inside the shellAdding a CLI definition to a '.pib.yml' fileThecli_definitionYAML key, should contain a list of definitions for CLI commands you wish to use.Each command should adhere to this format (and you can have many commands for whatever tasks you need to perform):-name:"command-name"description:"Adescriptionofthecommand."container_only:false# Optional restriction of the command to a PIB containerpath:"repo_root"commands:-"oneormore"-"shellcommands"-"eachruninadiscreteenvironment"-"The${PIB_DOCUMENTATION_ROOT}environmentvariableisalsoavailableifyouneedtonavigatetothatfolder."-"The${PIB_PROJECT_NAME}environmentvariableisavailableifyouneedtonavigatetothatfolder."-"Anyextraargumentspassedarestoredinthe${PIB_OVERLOAD_ARGUMENTS}environmentvariable."success:"SuccessMessage"failure:"FailureMessage"Notes on this configuration format:container_onlyrestricts the command to working only inside aPython-in-a-Boxcontainer environment.  (Completely optional key to include, defaults tofalse.)pathmust be one of:repo_root(The root folder of your code repository.)documentation_root(Defaults to the folderdocumentation, can be customized with metadata or environment variables.)project_root(Theproject_namefolder as defined with metadata or environment variables.)Validating a '.pib.yml' fileUsepib_clito validate new configuration files before activating them:dev @pib config -c <path to your file> validateActivating a '.pib.yml' fileToactivateyour configuration, use one of the following methods:You can set the environment variablePIB_CONFIG_FILE_LOCATIONto the absolute path where the file is located.Or just move your new.pib.ymlfile to the top level folder (the repository root) of your project.Use the commanddev @pib config whereto confirm it's been activated.If a.pib.ymlfile cannot be found with either of these methods, then thedefault configwill be used.Development Guide forpib_cliPlease see the documentationhere.Environment Variable SummaryThis table summarizes the environment variables that can be used withpib_cli:NamePurposePIB_CONFIG_FILE_LOCATIONThe absolute path to the configuration file that should be used.PIB_DOCUMENTATION_ROOTA relative path from the repository root where a Sphinx Makefile lives.PIB_OVERLOAD_ARGUMENTSReserved to pass arguments to customized CLI commands.PIB_PROJECT_NAMEThe top level folder in the repository where the codebase is found.