-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
10 changed files
with
559 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,18 +1,20 @@ | ||
# v0.2.3 | ||
# Changelog | ||
|
||
## v0.2.3 | ||
* Transfer the repo to click-contrib organisation | ||
|
||
# v0.2.2 | ||
## v0.2.2 | ||
* Add true lineno in warning when declaring empty option group | ||
* Update readme | ||
|
||
# v0.2.1 | ||
## v0.2.1 | ||
* Use RuntimeWarning and stacklevel 2 when declaring empty option group | ||
* Update readme | ||
|
||
# v0.2.0 | ||
## v0.2.0 | ||
* Implement `RequiredMutuallyExclusiveOptionGroup` class instead of `required` argument for `MutuallyExclusiveOptionGroup` | ||
* Add tests with 100% coverage | ||
* Update readme | ||
|
||
# v0.1.0 | ||
## v0.1.0 | ||
* First public release |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
SPHINXOPTS ?= | ||
SPHINXBUILD ?= sphinx-build | ||
SOURCEDIR = . | ||
BUILDDIR = _build | ||
|
||
# Put it first so that "make" without argument is like "make help". | ||
help: | ||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: help Makefile | ||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new | ||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
%: Makefile | ||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,93 @@ | ||
.. _api: | ||
|
||
API Reference | ||
============= | ||
|
||
.. currentmodule:: click_option_group | ||
|
||
.. autosummary:: | ||
:nosignatures: | ||
|
||
optgroup | ||
|
||
GroupedOption | ||
OptionGroup | ||
|
||
RequiredAnyOptionGroup | ||
RequiredAllOptionGroup | ||
MutuallyExclusiveOptionGroup | ||
RequiredMutuallyExclusiveOptionGroup | ||
|
||
| | ||
.. py:class:: optgroup | ||
A global instance of the helper class to manage creating groups and group options via decorators | ||
|
||
The class provides two decorator-methods: ``group``/``__call__`` and ``option``. | ||
These decorators should be used for adding grouped options. The class have | ||
single global instance ``optgroup`` that should be used in most cases. | ||
|
||
The example of usage:: | ||
|
||
from click_option_group import optgroup | ||
|
||
... | ||
@optgroup('Group 1', help='option group 1') | ||
@optgroup.option('--foo') | ||
@optgroup.option('--bar') | ||
@optgroup.group('Group 2', help='option group 2') | ||
@optgroup.option('--spam') | ||
... | ||
|
||
.. py:method:: group(name, *, cls, help, **attrs) | ||
The decorator creates a new group and collects its options | ||
|
||
Creates the option group and registers all grouped options | ||
which were added by :func:`option` decorator. | ||
|
||
:param name: Group name or None for deault name | ||
:param cls: Option group class that should be inherited from :class:`OptionGroup` class | ||
:param help: Group help or None for empty help | ||
:param attrs: Additional parameters of option group class | ||
|
||
.. py:method:: option(*param_decls, **attrs) | ||
The decorator adds a new option to the group | ||
|
||
The decorator is lazy. It adds option decls and attrs. | ||
All options will be registered by :func:`group` decorator. | ||
|
||
:param param_decls: option declaration tuple | ||
:param attrs: additional option attributes and parameters | ||
|
||
---- | ||
|
||
.. autoclass:: GroupedOption | ||
:members: | ||
|
||
---- | ||
|
||
.. autoclass:: OptionGroup | ||
:members: | ||
|
||
---- | ||
|
||
.. autoclass:: RequiredAnyOptionGroup | ||
:members: | ||
|
||
---- | ||
|
||
.. autoclass:: RequiredAllOptionGroup | ||
:members: | ||
|
||
---- | ||
|
||
.. autoclass:: MutuallyExclusiveOptionGroup | ||
:members: | ||
|
||
---- | ||
|
||
.. autoclass:: RequiredMutuallyExclusiveOptionGroup | ||
:members: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
.. _changelog: | ||
|
||
.. mdinclude:: ../CHANGELOG.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,83 @@ | ||
# Configuration file for the Sphinx documentation builder. | ||
# | ||
# This file only contains a selection of the most common options. For a full | ||
# list see the documentation: | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html | ||
|
||
# -- Path setup -------------------------------------------------------------- | ||
|
||
# If extensions (or modules to document with autodoc) are in another directory, | ||
# add these directories to sys.path here. If the directory is relative to the | ||
# documentation root, use os.path.abspath to make it absolute, like shown here. | ||
|
||
import os | ||
import sys | ||
|
||
sys.path.insert(0, os.path.abspath('.')) | ||
|
||
from pallets_sphinx_themes import ProjectLink | ||
from click_option_group import __version__ # noqa | ||
|
||
|
||
# -- Project information ----------------------------------------------------- | ||
|
||
project = 'click-option-group' | ||
copyright = '2020, Eugene Prilepin' | ||
author = 'Eugene Prilepin' | ||
|
||
# The full version, including alpha/beta/rc tags | ||
release = __version__ | ||
|
||
|
||
# -- General configuration --------------------------------------------------- | ||
|
||
# Add any Sphinx extension module names here, as strings. They can be | ||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom | ||
# ones. | ||
extensions = [ | ||
'sphinx.ext.autodoc', | ||
'sphinx.ext.autosummary', | ||
'sphinx.ext.intersphinx', | ||
'pallets_sphinx_themes', | ||
'm2r', | ||
] | ||
|
||
autodoc_member_order = 'bysource' | ||
|
||
intersphinx_mapping = { | ||
'Click': ('https://click.palletsprojects.com', None) | ||
} | ||
|
||
# Add any paths that contain templates here, relative to this directory. | ||
templates_path = ['_templates'] | ||
|
||
# List of patterns, relative to source directory, that match files and | ||
# directories to ignore when looking for source files. | ||
# This pattern also affects html_static_path and html_extra_path. | ||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] | ||
|
||
|
||
# -- Options for HTML output ------------------------------------------------- | ||
|
||
# The theme to use for HTML and HTML Help pages. See the documentation for | ||
# a list of builtin themes. | ||
# | ||
html_theme = 'click' | ||
|
||
html_context = { | ||
"project_links": [ | ||
ProjectLink("PyPI releases", "https://pypi.org/project/click-option-group/"), | ||
ProjectLink("Source Code", "https://github.com/click-contrib/click-option-group/"), | ||
ProjectLink("Issue Tracker", "https://github.com/click-contrib/click-option-group/issues/"), | ||
] | ||
} | ||
|
||
html_sidebars = { | ||
"index": ["project.html", "localtoc.html", "searchbox.html"], | ||
"**": ["localtoc.html", "relations.html", "searchbox.html"], | ||
} | ||
|
||
# Add any paths that contain custom static files (such as style sheets) here, | ||
# relative to this directory. They are copied after the builtin static files, | ||
# so a file named "default.css" will overwrite the builtin "default.css". | ||
html_static_path = ['_static'] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,79 @@ | ||
.. click-option-group documentation master file, created by | ||
sphinx-quickstart on Sat Jan 18 02:32:05 2020. | ||
You can adapt this file completely to your liking, but it should at least | ||
contain the root `toctree` directive. | ||
click-option-group | ||
================== | ||
|
||
**click-option-group** is a `Click <https://click.palletsprojects.com>`_-extension package | ||
that adds option groups missing in Click. | ||
|
||
Aim and Motivation | ||
------------------ | ||
|
||
Click is a package for creating powerful and beautiful command line interfaces (CLI) in Python, | ||
but it has no the functionality for creating option groups. | ||
|
||
Option groups are convenient mechanism for logical structuring CLI, also it allows you to set | ||
the specific behavior and set the relationship among grouped options (mutually exclusive options for example). | ||
Moreover, `argparse <https://docs.python.org/3/library/argparse.html>`_ stdlib package contains this | ||
functionality out of the box. | ||
|
||
At the same time, many Click users need this functionality. | ||
You can read interesting discussions about it in the following issues: | ||
|
||
* `issue 257 <https://github.com/pallets/click/issues/257>`_ | ||
* `issue 509 <https://github.com/pallets/click/issues/509>`_ | ||
* `issue 1137 <https://github.com/pallets/click/issues/1137>`_ | ||
|
||
The aim of this package is to provide group options with extensible functionality | ||
using canonical and clean API (Click-like API as far as possible). | ||
|
||
Installing | ||
---------- | ||
|
||
You can install and update click-option-group using pip:: | ||
|
||
pip install -U click-option-group | ||
|
||
Quickstart | ||
---------- | ||
|
||
Here is a simple example how to use option groups in your Click-based CLI. | ||
|
||
.. code-block:: python | ||
import click | ||
from click_option_group import optgroup | ||
@click.command() | ||
@optgroup.group('Server configuration', | ||
help='The configuration of some server connection') | ||
@optgroup.option('-h', '--host', default='localhost', help='Server host name') | ||
@optgroup.option('-p', '--port', type=int, default=8888, help='Server port') | ||
@click.option('--debug/--no-debug', default=False, help='Debug flag') | ||
def cli(host, port, debug): | ||
print(params) | ||
if __name__ == '__main__': | ||
cli() | ||
Contents | ||
-------- | ||
|
||
.. toctree:: | ||
:maxdepth: 2 | ||
|
||
manual | ||
api | ||
changelog | ||
|
||
|
||
Indices and tables | ||
================== | ||
|
||
* :ref:`genindex` | ||
* :ref:`modindex` | ||
* :ref:`search` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
@ECHO OFF | ||
|
||
pushd %~dp0 | ||
|
||
REM Command file for Sphinx documentation | ||
|
||
if "%SPHINXBUILD%" == "" ( | ||
set SPHINXBUILD=sphinx-build | ||
) | ||
set SOURCEDIR=. | ||
set BUILDDIR=_build | ||
|
||
if "%1" == "" goto help | ||
|
||
%SPHINXBUILD% >NUL 2>NUL | ||
if errorlevel 9009 ( | ||
echo. | ||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx | ||
echo.installed, then set the SPHINXBUILD environment variable to point | ||
echo.to the full path of the 'sphinx-build' executable. Alternatively you | ||
echo.may add the Sphinx directory to PATH. | ||
echo. | ||
echo.If you don't have Sphinx installed, grab it from | ||
echo.http://sphinx-doc.org/ | ||
exit /b 1 | ||
) | ||
|
||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
goto end | ||
|
||
:help | ||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
|
||
:end | ||
popd |
Oops, something went wrong.