-.. todo:: THIS IS SUPPOSED TO BE AN EXAMPLE. MODIFY IT ACCORDING TO YOUR NEEDS!
-
- The document assumes you are using a source repository service that promotes a
- contribution model similar to `GitHub's fork and pull request workflow`_.
- While this is true for the majority of services (like GitHub, GitLab,
- BitBucket), it might not be the case for private repositories (e.g., when
- using Gerrit).
-
- Also notice that the code examples might refer to GitHub URLs or the text
- might use GitHub specific terminology (e.g., *Pull Request* instead of *Merge
- Request*).
-
- Please make sure to check the document having these assumptions in mind
- and update things accordingly.
-
-.. todo:: Provide the correct links/replacements at the bottom of the document.
-
-.. todo:: You might want to have a look on `PyScaffold's contributor's guide`_,
-
- especially if your project is open source. The text should be very similar to
- this template, but there are a few extra contents that you might decide to
- also include, like mentioning labels of your issue tracker or automated
- releases.
-
-
============
Contributing
============
This means that the docs are kept in the same repository as the project code, and
that any documentation update is done in the same way was a code contribution.
-.. todo:: Don't forget to mention which markup language you are using.
-
- e.g., reStructuredText_ or CommonMark_ with MyST_ extensions.
-
-.. todo:: If your project is hosted on GitHub, you can also mention the following tip:
+Documentation is written in reStructuredText_ format
- .. tip::
- Please notice that the `GitHub web interface`_ provides a quick way of
- propose changes in ``python-one-password``'s files. While this mechanism can
- be tricky for normal code contributions, it works perfectly fine for
- contributing to the docs, and can be quite handy.
-
- If you are interested in trying this method out, please navigate to
- the ``docs`` folder in the source repository_, find which file you
- would like to propose changes and click in the little pencil icon at the
- top, to open `GitHub's code editor`_. Once you finish editing the file,
- please write a message in the form at the bottom of the page describing
- which changes have you made and what are the motivations behind them and
- submit your proposal.
+.. tip::
+ Please notice that the `GitHub web interface`_ provides a quick way of
+ propose changes in ``python-one-password``'s files. While this mechanism can
+ be tricky for normal code contributions, it works perfectly fine for
+ contributing to the docs, and can be quite handy.
+
+ If you are interested in trying this method out, please navigate to
+ the ``docs`` folder in the source repository_, find which file you
+ would like to propose changes and click in the little pencil icon at the
+ top, to open `GitHub's code editor`_. Once you finish editing the file,
+ please write a message in the form at the bottom of the page describing
+ which changes have you made and what are the motivations behind them and
+ submit your proposal.
When working on documentation changes in your local machine, you can
compile them using |tox|_::
Code Contributions
==================
-.. todo:: Please include a reference or explanation about the internals of the project.
-
- An architecture description, design principles or at least a summary of the
- main concepts will make it easy for potential contributors to get started
- quickly.
+This tool uses the typer module to implement much of its functionality.
+Familiarity with this will be of great benefit if you intend to contribute.
Submit an issue
---------------
page. This creates a copy of the code under your account on |the repository service|.
#. Clone this copy to your local disk::
- git clone git@github.com:YourLogin/python-one-password.git
+ git clone https://github.com/lfit/releng-python-one-password.git
cd python-one-password
#. You should run::
to be able to import the package under development in the Python REPL.
- .. todo:: if you are not using pre-commit, please remove the following item:
-
#. Install |pre-commit|_::
pip install pre-commit
to record your changes in git_.
- .. todo:: if you are not using pre-commit, please remove the following item:
-
Please make sure to see the validation messages from |pre-commit|_ and fix
any eventual issues.
This should automatically use flake8_/black_ to check/fix the code style
#. Go to the web page of your fork and click |contribute button|
to send your changes for review.
- .. todo:: if you are using GitHub, you can uncomment the following paragraph
-
Find more detailed information in `creating a PR`_. You might also want to open
the PR as a draft first and mark it as ready for review after the feedbacks
from the continuous integration (CI) system or any required fixes.
Releases
--------
-.. todo:: This section assumes you are using PyPI to publicly release your package.
-
- If instead you are using a different/private package index, please update
- the instructions accordingly.
-
If you are part of the group of maintainers and have correct user permissions
on PyPI_, the following steps can be used to release a new version for
``python-one-password``:
.. <-- start -->
-.. todo:: Please review and change the following definitions:
-
.. |the repository service| replace:: GitHub
.. |contribute button| replace:: "Create pull request"
-.. _repository: https://github.com/<USERNAME>/python-one-password
-.. _issue tracker: https://github.com/<USERNAME>/python-one-password/issues
+.. _repository: https://github.com/lfit/releng-python-one-password
+.. _issue tracker: https://github.com/lfit/releng-python-one-password/issues
.. <-- end -->
.. _black: https://pypi.org/project/black/
-.. _CommonMark: https://commonmark.org/
.. _contribution-guide.org: https://www.contribution-guide.org/
.. _creating a PR: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
.. _descriptive commit message: https://chris.beams.io/posts/git-commit
.. _docstrings: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
-.. _first-contributions tutorial: https://github.com/firstcontributions/first-contributions
.. _flake8: https://flake8.pycqa.org/en/stable/
.. _git: https://git-scm.com
-.. _GitHub's fork and pull request workflow: https://guides.github.com/activities/forking/
.. _guide created by FreeCodeCamp: https://github.com/FreeCodeCamp/how-to-contribute-to-open-source
.. _Miniconda: https://docs.conda.io/en/latest/miniconda.html
-.. _MyST: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html
.. _other kinds of contributions: https://opensource.guide/how-to-contribute
.. _pre-commit: https://pre-commit.com/
.. _PyPI: https://pypi.org/
-.. _PyScaffold's contributor's guide: https://pyscaffold.org/en/stable/contributing.html
.. _Pytest can drop you: https://docs.pytest.org/en/stable/how-to/failures.html#using-python-library-pdb-with-pytest
.. _Python Software Foundation's Code of Conduct: https://www.python.org/psf/conduct/
.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/
-.. These are examples of badges you might want to add to your README:
- please update the URLs accordingly
-
- .. image:: https://api.cirrus-ci.com/github/<USER>/python-one-password.svg?branch=main
- :alt: Built Status
- :target: https://cirrus-ci.com/github/<USER>/python-one-password
- .. image:: https://readthedocs.org/projects/python-one-password/badge/?version=latest
- :alt: ReadTheDocs
- :target: https://python-one-password.readthedocs.io/en/stable/
- .. image:: https://img.shields.io/coveralls/github/<USER>/python-one-password/main.svg
- :alt: Coveralls
- :target: https://coveralls.io/r/<USER>/python-one-password
- .. image:: https://img.shields.io/pypi/v/python-one-password.svg
- :alt: PyPI-Server
- :target: https://pypi.org/project/python-one-password/
- .. image:: https://img.shields.io/conda/vn/conda-forge/python-one-password.svg
- :alt: Conda-Forge
- :target: https://anaconda.org/conda-forge/python-one-password
- .. image:: https://pepy.tech/badge/python-one-password/month
- :alt: Monthly Downloads
- :target: https://pepy.tech/project/python-one-password
- .. image:: https://img.shields.io/twitter/url/http/shields.io.svg?style=social&label=Twitter
- :alt: Twitter
- :target: https://twitter.com/python-one-password
+
+
+.. image:: https://img.shields.io/badge/python-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54
+ :alt: Project generated in Python
+ :target: https://www.python.org/
.. image:: https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold
:alt: Project generated with PyScaffold
The python-one-password tool and its dependencies can be installed from PyPI
using the standard Python PIP command:
-``
-% python3 -m pip install python_one_password
-``
+``% python3 -m pip install python_one_password``
Interactive Help
================
The primary command and sub-commands have embedded help, which can be accessed
-as shown below:
+as shown below::
-``
-% python-one-password --help
-% python-one-password credentials --help
-% python-one-password tags --help
-``
+ % python-one-password --help
+ % python-one-password credentials --help
+ % python-one-password tags --help
Importing Credentials
Note: supply your password and/or biometric data to unlock the 1Password database if/when prompted
-You can then import credentials from one or more vaults, as shown below for a vault called "Testing":
-
-``
- % python-one-password credentials fetch -n -i Testing
-Importing data from 1Password database...
-Total number of vaults: 20
-Vaults imported into cache: 1
+You can then import credentials from one or more vaults, as shown below for a vault called "Testing"::
-########## Vault Summary ##########
+ % python-one-password credentials fetch -n -i Testing
+ Importing data from 1Password database...
+ Total number of vaults: 20
+ Vaults imported into cache: 1
-ID Name
-cnx76s6avkg3xikw6u5bf7jdki Testing
+ ########## Vault Summary ##########
-Importing credential metadata from 1Password database...
-Credential data gathered for: 1 vault(s)
-Credential metadata records loaded: 5
-Loaded cached JSON metadata: [5] records
+ ID Name
+ cnx76s6avkg3xikw6u5bf7jdki Testing
-Review current credential state? (y/n): y
+ Importing credential metadata from 1Password database...
+ Credential data gathered for: 1 vault(s)
+ Credential metadata records loaded: 5
+ Loaded cached JSON metadata: [5] records
-### Credentials: Current State ###
+ Review current credential state? (y/n): y
-yczzflaacyziwew2ahy24kqdxi Test4
-gbikz2upboavuksupx65xb5fie Test5
-fkn3cp42ouua47rqtnergchm6q Test3
-rfoxd64sumvzbk2m7nkruyvr5e Test1
-xiu64ukcwxtxfco7j2wjcf36eq Test2
+ ### Credentials: Current State ###
-``
+ yczzflaacyziwew2ahy24kqdxi Test4
+ gbikz2upboavuksupx65xb5fie Test5
+ fkn3cp42ouua47rqtnergchm6q Test3
+ rfoxd64sumvzbk2m7nkruyvr5e Test1
+ xiu64ukcwxtxfco7j2wjcf36eq Test2
-Once a set of credentials have been loaded, you can review them with:
+Once a set of credentials have been loaded, you can review them with::
-``
-% python-one-password credentials show
-Loaded cached JSON metadata: [5] records
+ % python-one-password credentials show
+ Loaded cached JSON metadata: [5] records
-### Credentials: Current State ###
+ ### Credentials: Current State ###
-gbikz2upboavuksupx65xb5fie [] Test5
-fkn3cp42ouua47rqtnergchm6q ['c3po', 'luke', 'r2d2', 'chewbacca'] Test3
-yczzflaacyziwew2ahy24kqdxi [] Test4
-rfoxd64sumvzbk2m7nkruyvr5e ['c3po', 'luke', 'chewbacca'] Test1
-xiu64ukcwxtxfco7j2wjcf36eq ['c3po', 'luke', 'r2d2', 'chewbacca'] Test2
-``
+ gbikz2upboavuksupx65xb5fie [] Test5
+ fkn3cp42ouua47rqtnergchm6q ['c3po', 'luke', 'r2d2', 'chewbacca'] Test3
+ yczzflaacyziwew2ahy24kqdxi [] Test4
+ rfoxd64sumvzbk2m7nkruyvr5e ['c3po', 'luke', 'chewbacca'] Test1
+ xiu64ukcwxtxfco7j2wjcf36eq ['c3po', 'luke', 'r2d2', 'chewbacca'] Test2
-You can subsequently refine your selection using match/reject search patterns:
+You can subsequently refine your selection using match/reject search patterns::
-``
- % python-one-password credentials refine --reject chewbacca
-Loaded cached JSON metadata: [5] records
-Matching query: [3] chewbacca
-Subsequently rejected: 3/5
+ % python-one-password credentials refine --reject chewbacca
+ Loaded cached JSON metadata: [5] records
+ Matching query: [3] chewbacca
+ Subsequently rejected: 3/5
-Credentials now selected: 2
+ Credentials now selected: 2
-Review current credential state? (y/n): y
+ Review current credential state? (y/n): y
-### Credentials: Current State ###
+ ### Credentials: Current State ###
-yczzflaacyziwew2ahy24kqdxi [] Test4
-gbikz2upboavuksupx65xb5fie [] Test5
+ yczzflaacyziwew2ahy24kqdxi [] Test4
+ gbikz2upboavuksupx65xb5fie [] Test5
-Update working credential set to selection? (y/n): y
-``
+ Update working credential set to selection? (y/n): y
When you have obtained a suitable set of credentials to work with, you can move
on to tag manipulation.
-Working with tags
+Working with Tags
=================
The help for tag manipulation can be called up as follows:
-``
-% python-one-password tags --help
-``
+``% python-one-password tags --help``
The basic tag operations are:
useful where you have a list of team members (staff) who might be assigned a
set of credential as part of a rotation task/project. You can specify a list of
team members on the command-line and the list will be iterated over, allocating
-credentials in a round-robin fashion.
+credentials in a round-robin fashion.::
-``
- % python-one-password tags allocate -o bob sarah steve
-Loaded cached JSON metadata: [5] records
+ % python-one-password tags allocate -o bob sarah steve
+ Loaded cached JSON metadata: [5] records
-Review current credential state? (y/n): y
+ Review current credential state? (y/n): y
-### Credentials: Current State ###
+ ### Credentials: Current State ###
-gbikz2upboavuksupx65xb5fie [] Test5
-yczzflaacyziwew2ahy24kqdxi [] Test4
-fkn3cp42ouua47rqtnergchm6q ['c3po', 'luke', 'r2d2', 'chewbacca'] Test3
-rfoxd64sumvzbk2m7nkruyvr5e ['c3po', 'luke', 'chewbacca'] Test1
-xiu64ukcwxtxfco7j2wjcf36eq ['c3po', 'luke', 'r2d2', 'chewbacca'] Test2
+ gbikz2upboavuksupx65xb5fie [] Test5
+ yczzflaacyziwew2ahy24kqdxi [] Test4
+ fkn3cp42ouua47rqtnergchm6q ['c3po', 'luke', 'r2d2', 'chewbacca'] Test3
+ rfoxd64sumvzbk2m7nkruyvr5e ['c3po', 'luke', 'chewbacca'] Test1
+ xiu64ukcwxtxfco7j2wjcf36eq ['c3po', 'luke', 'r2d2', 'chewbacca'] Test2
-Tags to allocate: ['bob', 'sarah', 'steve']
+ Tags to allocate: ['bob', 'sarah', 'steve']
-### Credentials: Future State ###
+ ### Credentials: Future State ###
-gbikz2upboavuksupx65xb5fie ['bob'] Test5
-yczzflaacyziwew2ahy24kqdxi ['sarah'] Test4
-fkn3cp42ouua47rqtnergchm6q ['steve'] Test3
-rfoxd64sumvzbk2m7nkruyvr5e ['bob'] Test1
-xiu64ukcwxtxfco7j2wjcf36eq ['sarah'] Test2
+ gbikz2upboavuksupx65xb5fie ['bob'] Test5
+ yczzflaacyziwew2ahy24kqdxi ['sarah'] Test4
+ fkn3cp42ouua47rqtnergchm6q ['steve'] Test3
+ rfoxd64sumvzbk2m7nkruyvr5e ['bob'] Test1
+ xiu64ukcwxtxfco7j2wjcf36eq ['sarah'] Test2
-Commit these updates to the 1Password database? (y/n): y
-[5] Credentials updated
-``
+ Commit these updates to the 1Password database? (y/n): y
+ [5] Credentials updated
-.. _pyscaffold-notes:
-
Making Changes & Contributing
=============================
This project uses `pre-commit`_, please make sure to install it before making
-any changes:
+any changes::
-``
-% pip install pre-commit
-% cd python-one-password
-% pre-commit install
-``
+ % pip install pre-commit
+ % cd python-one-password
+ % pre-commit install
It is a good idea to update the hooks to the latest version::
-``
-% pre-commit autoupdate
-``
+``% pre-commit autoupdate``
Don't forget to tell your contributors to also install and use pre-commit.
.. _pre-commit: https://pre-commit.com/
-
-Note
-====
-
-This project has been set up using PyScaffold 4.4. For details and usage
-information on PyScaffold see https://pyscaffold.org/.
Code Review / releng / python-one-password.git / commitdiff