Merge pull request #2 from britive/develop

Develop

Author: twratl

.DS_Store

@@ -3,6 +3,11 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+.in
+.out
+.idea*
+testing-variables.txt
+
 # C extensions
 *.so
 

.gitignore

@@ -0,0 +1,193 @@
+# BETA - NOTE: This is a BETA release. This codebase should not be used for production workloads.
+
+# Britive CLI - Pure Python Implementation
+
+
+## Requirements
+
+* Python 3.7 or higher
+* Active Britive tenant (or nothing is really going to work)
+
+## Installation
+
+`pybritive` will be installed via Python `pip`. The package is not available in PyPi at this time, so it will be 
+installed via the published tar balls in the GitHub repo.
+
+~~~bash
+pip install https://github.com/britive/python-cli/releases/download/v0.1.0/pybritive-0.1.0.tar.gz
+~~~
+
+The end user is free to install the CLI into a virtual environment or in the global scope, so it is available
+everywhere.
+
+## Tenant Configuration
+
+Before `pybritive` can connect to a Britive tenant, it needs to know some details about that tenant.
+This is where `pybritive configure` will help us.
+
+There are 2 ways to tell `pybritive` about tenants.
+
+1. `pybritive configure import`: this will import an existing configuration from the Node.js version of the Britive CLI.
+2. `pybritive configure tenant`: This will prompt (or optionally the values can be passed via flags) for tenant details.
+
+An alias for a tenant can be created in case more than 1 tenant is configured for use. This may be the case for admins
+who may have access to an EA and GA tenant.
+
+## Tenant Selection Logic
+
+There are numerous ways to provide the CLI with the Britive tenant that should be used. The below list is the
+order of operations for determining the tenant.
+
+The tenant excludes `.britive-app.com`. Just include the leftmost part.
+Example: `example.britive-app.com` will have a tenant name in the CLI of `example`.
+
+1. Value retrieved from CLI option/flag `--tenant/-t`
+2. Value retrieved from environment variable `BRITIVE_TENANT`
+3. Value retrieved from `~/.britive/pybritive.config` global variable `default_tenant`
+4. If none of the above are available then check for configured tenants in `~/.britive/pybritive.config` and if there is only 1 tenant configured use it
+5. If all the above fail then error
+
+
+## Credential Selection Logic
+
+There are numerous ways to provide the CLI with the Britive credentials that should be used to authenticate to the
+Britive tenant. The below list is the order of operations for determining the tenant.
+
+1. Value retrieved from CLI option/flag `--token/-T`
+2. Value retrieved from environment variable `BRITIVE_API_TOKEN`
+3. If none of the above are available an interactive login will be performed and temporary credentials will be stored locally for future use with the CLI
+
+
+## Credential Stores
+
+The CLI currently offers two ways in which temporary credentials obtained via interactive login can be stored.
+Future enhancements aim to offer other credential storage options.
+
+### File
+
+Credentials will be stored in a plaintext file located at `~/.britive/pybritive.credentials`
+
+### Encrypted File
+Credentials will be stored in an encrypted file located at `~/.britive/pybritive.credentials.encrypted`.
+
+The user will be prompted for a passphrase to use to encrypt the file. The user can also pass in the passphrase
+via flag `--passphrase/-p` or via environment variable `PYBRITIVE_ENCRYPTED_CREDENTIAL_PASSPHRASE`.
+
+
+## Home Directory
+By default, files that `pybritive` requires will be persisted to `~/.britive/`. 
+
+This can be overwritten by specifying environment variable `PYBRITIVE_HOME_DIR`. This should be a path to where
+the end user wants to persist the `.britive` directory. Note that `.britive` will still be created so do not specify
+that as part of the path.
+
+## Shell Completion
+Behind the scenes the `pybritive` CLI tool uses the python `click` package. `click` offers shell completion for
+the following shells.
+
+* Bash
+* Zsh
+* Fish
+* PowerShell (work in progress for the `pybritive` cli - NOT WORKING YET)
+
+In order to set up shell completion, follow these steps. Once complete either `source` your environment again
+or start a new shell in order for the changes to be loaded.
+
+### Bash
+Save the completion script somewhere.
+
+~~~bash
+_PYBRITIVE_COMPLETE=bash_source pybritive > ~/.pybritive-complete.bash
+~~~
+
+Source the file in `~/.bashrc`.
+
+~~~
+source ~/.pybritive-complete.bash
+~~~
+
+### Zsh
+Save the completion script somewhere.
+
+~~~bash
+_PYBRITIVE_COMPLETE=zsh_source pybritive > ~/.pybritive-complete.zsh
+~~~
+
+Source the file in `~/.zshrc`.
+
+~~~
+source ~/.pybritive-complete.zsh
+~~~
+
+### Fish
+Save the completion script to the `fish` completions directory.
+
+~~~bash
+_PYBRITIVE_COMPLETE=fish_source pybritive > ~/.config/fish/completions/foo-bar.fish
+~~~
+
+### PowerShell
+Append the below code to your PowerShell profile.
+
+~~~
+if ((Test-Path Function:\TabExpansion) -and -not (Test-Path Function:\pybritiveTabExpansionBackup)) {
+    Rename-Item Function:\TabExpansion pybritiveTabExpansionBackup
+}
+
+function TabExpansion($line, $lastWord) {
+    $lastBlock = [regex]::Split($line, '[|;]')[-1].TrimStart()
+    $aliases = @("pybritive") + @(Get-Alias | where { $_.Definition -eq "pybritive" } | select -Exp Name)
+    $aliasPattern = "($($aliases -join '|'))"
+    if($lastBlock -match "^$aliasPattern ") {
+        $Env:_PYBRITIVE_COMPLETE = "complete-powershell"
+        $Env:COMMANDLINE = "$lastBlock"
+        (pybritive) | ? {$_.trim() -ne "" }
+        Remove-Item Env:_PYBRITIVE_COMPLETE
+        Remove-Item Env:COMMANDLINE
+    }
+    elseif (Test-Path Function:\pybritiveTabExpansionBackup) {
+        # Fall back on existing tab expansion
+        pybritiveTabExpansionBackup $line $lastWord
+    }
+}
+~~~
+
+
+The location of your PowerShell profile can be found with command
+
+~~~bash
+echo $profile
+~~~
+
+And is generally something like `C:\Users\{user}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`.
+
+### Shell Completion - Profiles - Local Cache
+
+By default, shell completion only completes commands and options/flags as those values are available without
+any authentication to a Britive tenant.
+
+There is an option to enable shell completion for profiles and profile aliases for use with `checkout` and `checkin`.
+
+In order enable this, run the following command.
+
+~~~bash
+pybritive cache profiles
+~~~
+
+This will locally cache profiles for which the authenticated user has permissions. If multiple tenants are being used
+then each tenant will need to be cached individually. All profiles across all tenants will be available during shell
+completion.
+
+The cache will not be updated over time. In order to update the cache more regularly run the following command.
+Note that this config flag is NOT available directly via `pybrtitve configure global ...`.
+
+~~~bash
+pybritive configure update global auto-refresh-profile-cache true
+~~~
+
+To turn the feature off run
+
+~~~bash
+pybritive configure update global auto-refresh-profile-cache false
+pybritive cache clear
+~~~

README.md

@@ -0,0 +1,43 @@
+## Local Install
+
+~~~
+pip install --editable .
+~~~
+
+## Build
+
+* Update version in `setup.cfg`
+* Push code to GitHub
+* Cut a new PR and merge when appropriate
+* Run below commands
+
+
+~~~
+python -m pip install --upgrade build
+python -m build
+~~~
+
+* Cut a new release in GitHub with the version tag
+* Add the assets from `dist` directory to the release
+
+## Testing
+It is generally advisable to set environment variable `PYBRITIVE_HOME_DIR` to some temp location if you
+will be performing the full suite of tests. This will ensure that no changes are made to your existing
+configuration or credentials.
+
+Environment variables that should be set for testing include the following.
+
+* `PYBRITIVE_HOME_DIR` - a path to a home directory where `.britive` directory will be created
+* `PYBRITIVE_TEST_TENANT` - the tenant name to be used for testing purposes
+* `PYBRITIVE_NPM_IMPORT_PROFILE_ALIAS_VALUE` - the IDs of a profile that can be used to test the import process. This should be in format `"appid/envid/profileid/appname"`.
+* `PYBRITIVE_ENCRYPTED_CREDENTIAL_PASSPHRASE` - the password for encrypted file credential storage
+* `PYBRITIVE_PREPARE_DOT_BRITIVE` - set to true if you want to have the `.britive` directory cleared before starting the tests
+* `BRITIVE_API_TOKEN` - set if you want to avoid an interactive login process - the interactive login process will need to be tested separately
+
+Create `./testing-variables.txt` and load what you need so you can easily re-create the needed variables. This file is in `.gitignore`. 
+
+The identity used for testing will require access to at least one profile to test `checkout` and `checkin`. 
+Additionally, the identity will need access to 2 secrets
+* one standard secret with path `/pybritive-test-standard` to test `view` - the value of the secret should be generic note with note of `test`
+* one file secret with path `/pybritive-test-file` to test `download` - the filename should be `pybritive-test-secret-file.txt` and contain contents of `test`
+

TECH_README.md

@@ -0,0 +1,6 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"

pyproject.toml

@@ -0,0 +1,14 @@
+https://github.com/britive/python-sdk/releases/download/v2.7.0/britive-2.7.0.tar.gz
+certifi==2022.6.15
+charset-normalizer==2.1.0
+click==8.1.3
+idna==3.3
+merge-args==0.1.4
+PyYAML==6.0
+requests==2.28.1
+six==1.16.0
+tabulate==0.8.10
+toml==0.10.2
+urllib3==1.26.9
+cryptography==37.0.4
+pytest==7.1.2

requirements.txt

@@ -0,0 +1,35 @@
+[metadata]
+name = pybritive
+version = 0.1.0
+author = Britive Inc.
+author_email = support@britive.com
+description = A pure Python CLI for Britive
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://www.britive.com
+classifiers =
+    Programming Language :: Python :: 3
+    License :: OSI Approved :: MIT License
+    Operating System :: OS Independent
+
+[options]
+package_dir =
+    = src
+packages = find:
+python_requires = >=3.7
+install_requires =
+    click
+    requests
+    PyYAML
+    merge_args
+    tabulate
+    toml
+    cryptography
+    britive @ https://github.com/britive/python-sdk/releases/download/v2.7.0/britive-2.7.0.tar.gz#egg=britive-2.7.0
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+console_scripts =
+    pybritive = pybritive.cli_interface:safe_cli

setup.cfg

@@ -0,0 +1 @@
+