Skip to content

Commit c47fe6f

Browse files
akimrxakimrx
authored
docs: added Sphinx autodoc (#2)
* chore: updated dev requirements, install * docs: added sphinx, updated docstrings
1 parent b2dbc33 commit c47fe6f

70 files changed

Lines changed: 9580 additions & 5 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Yandex Lockbox Client
22

3-
This client is a simple library for working with **[Yandex Lockbox](https://cloud.yandex.ru/en/docs/lockbox/)** over [REST API](https://cloud.yandex.ru/en/docs/lockbox/api-ref/), simplifying work with secrets and allowing you to work with them in the OOP paradigm.
3+
This library is a simple client for working with **[Yandex Lockbox](https://cloud.yandex.ru/en/docs/lockbox/)** over [REST API](https://cloud.yandex.ru/en/docs/lockbox/api-ref/), simplifying work with secrets and allowing you to work with them in the OOP paradigm.
44

55

66
**Supported Python versions**:

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = static
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/conf.py‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
import os
10+
import sys
11+
12+
sys.path.insert(0, os.path.abspath("../.."))
13+
14+
import yc_lockbox
15+
16+
17+
project = "yc-lockbox"
18+
copyright = "2024, Akim Faskhutdinov"
19+
author = yc_lockbox.__author__
20+
release = yc_lockbox.__version__
21+
22+
# -- General configuration ---------------------------------------------------
23+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
24+
25+
26+
extensions = [
27+
"sphinx.ext.autodoc",
28+
"sphinx.ext.viewcode",
29+
"sphinx_autodoc_typehints",
30+
"sphinx_copybutton",
31+
"sphinxcontrib.autodoc_pydantic",
32+
]
33+
34+
35+
templates_path = ["_templates"]
36+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
37+
38+
# Pydantic settings
39+
autodoc_pydantic_model_show_json = False
40+
autodoc_pydantic_settings_show_json = False
41+
autodoc_pydantic_model_show_config_summary = False
42+
43+
44+
# -- Options for HTML output -------------------------------------------------
45+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
46+
47+
try:
48+
import furo
49+
50+
html_theme = "furo" # https://pradyunsg.me/furo/
51+
except ImportError:
52+
html_theme = "alabaster"
53+
54+
html_static_path = ["_static"]
55+
html_title = "Yandex Lockbox Python client documentation"

‎docs/source/index.rst‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
.. yc-lockbox documentation master file, created by
2+
sphinx-quickstart on Sun Mar 24 11:23:54 2024.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Yandex Lockbox Python client documentation
7+
==========================================
8+
9+
Release v\ |release|
10+
11+
This library is a simple client for working with `Yandex Lockbox <https://cloud.yandex.ru/en/docs/lockbox/>`_ over `REST API <https://cloud.yandex.ru/en/docs/lockbox/api-ref/>`_, simplifying work with secrets and allowing you to work with them in the OOP paradigm.
12+
13+
------------------------------
14+
15+
**Supported Python versions**:
16+
17+
* 3.10
18+
19+
* 3.11
20+
21+
* 3.12
22+
23+
**Dependencies:**
24+
25+
* `PydanticV2 <https://github.com/pydantic/pydantic>`_
26+
27+
* `Crypthography <https://github.com/pyca/cryptography>`_
28+
29+
* `PyJWT <https://github.com/jpadilla/pyjwt>`_
30+
31+
* `Requests <https://github.com/psf/requests>`_
32+
33+
34+
**Currently, the following operations are not supported by the library:**
35+
36+
* List secret access bindings
37+
38+
* Set secret access bindings
39+
40+
* Update secret access bindings
41+
42+
* List secret operations
43+
44+
45+
Installation
46+
------------
47+
48+
Installing with pip:
49+
50+
.. code-block:: shell
51+
52+
pip install yc-lockbox
53+
54+
55+
Also, you can install from source with:
56+
57+
.. code-block:: shell
58+
59+
git clone https://github.com/akimrx/python-yc-lockbox
60+
cd python-yc-lockbox
61+
make install
62+
63+
64+
65+
Quick start
66+
------------
67+
68+
69+
* Authenticate via your OAuth token
70+
71+
.. code-block:: python
72+
73+
from yc_lockbox import YandexLockboxClient
74+
75+
lockbox = YandexLockboxClient("y0_xxxxxxxxxxxx")
76+
77+
78+
* Authenticate via `IAM token <https://cloud.yandex.com/en/docs/iam/operations/iam-token/create>`_
79+
80+
.. note::
81+
82+
If you pass a IAM token as credentials, you need to take care of the freshness of the token yourself.
83+
84+
85+
.. code-block:: python
86+
87+
from yc_lockbox import YandexLockboxClient
88+
89+
lockbox = YandexLockboxClient("t1.xxxxxx.xxxxxxx")
90+
91+
92+
* Authenticate using `service account key <https://cloud.yandex.com/en/docs/iam/operations/authorized-key/create#cli_1>`_
93+
94+
.. code-block:: python
95+
96+
import json
97+
from yc_lockbox import YandexLockboxClient
98+
99+
with open("/path/to/key.json", "r") as keyfile:
100+
credentials = keyfile.read()
101+
102+
lockbox = YandexLockboxClient(credentials)
103+
104+
105+
106+
Create a new secret
107+
^^^^^^^^^^^^^^^^^^^
108+
109+
110+
.. code-block:: python
111+
112+
from yc_lockbox import YandexLockboxClient, INewSecret, INewSecretPayloadEntry
113+
114+
lockbox = YandexLockboxClient("oauth_or_iam_token")
115+
116+
create_secret_operation = lockbox.create_secret(
117+
INewSecret(
118+
folder_id="b1xxxxxxxxxxxxxx",
119+
name="my-secret",
120+
version_payload_entries=[
121+
INewSecretPayloadEntry(key="secret_entry_1", text_value="secret_entry_text_value"),
122+
INewSecretPayloadEntry(key="secret_entry_2", binary_value="secret_entry_binary_value".encode()),
123+
],
124+
)
125+
)
126+
127+
if create_secret_operation.done:
128+
new_secret = create_secret_operation.resource
129+
print(new_secret.id)
130+
new_secret.deactivate()
131+
132+
133+
134+
Get secret from Lockbox
135+
^^^^^^^^^^^^^^^^^^^^^^^
136+
137+
.. code-block:: python
138+
139+
from yc_lockbox import YandexLockboxClient, Secret
140+
141+
lockbox = YandexLockboxClient("oauth_or_iam_token")
142+
143+
secret: Secret = lockbox.get_secret("e6qxxxxxxxxxx")
144+
print(secret.status, secret.name)
145+
146+
payload = secret.payload(version_id=secret.current_version.id) # id is optional, by default using current version
147+
print(payload.entries) # list of SecretPayloadEntry objects
148+
149+
# Direct access
150+
151+
entry = payload["secret_entry_1"] # or payload.get("secret_entry_1")
152+
153+
print(entry.text_value) # return MASKED value like ***********
154+
print(entry.reveal_text_value()) # similar to entry.text_value.get_secret_value()
155+
156+
157+
158+
Add new version of secret
159+
^^^^^^^^^^^^^^^^^^^^^^^^^
160+
161+
.. code-block:: python
162+
163+
from yc_lockbox import YandexLockboxClient, Secret, INewSecretVersion, INewSecretPayloadEntry
164+
165+
lockbox = YandexLockboxClient("oauth_or_iam_token")
166+
167+
secret: Secret = lockbox.get_secret("e6qxxxxxxxxxxxx")
168+
169+
secret.add_version(
170+
INewSecretVersion(
171+
description="a new version",
172+
base_version_id=secret.current_version.id,
173+
payload_entries= [
174+
INewSecretPayloadEntry(key="secret_entry_1", text_value="secret_entry_text_value"),
175+
INewSecretPayloadEntry(key="secret_entry_2", binary_value="secret_entry_binary_value"),
176+
]
177+
)
178+
)
179+
180+
# alternative
181+
lockbox.add_secret_version(
182+
"secret_id",
183+
version=INewSecretVersion(
184+
description="a new version",
185+
base_version_id=secret.current_version.id,
186+
payload_entries=[INewSecretPayloadEntry(...), INewSecretPayloadEntry(...)]
187+
)
188+
)
189+
190+
191+
192+
Other operations with secret
193+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
194+
195+
.. code-block:: python
196+
197+
from yc_lockbox import YandexLockboxClient
198+
199+
lockbox = YandexLockboxClient("oauth_or_iam_token")
200+
201+
202+
for secret in lockbox.list_secrets(folder_id="b1xxxxxxxxxx", iterator=True):
203+
print(secret.name, secret.status)
204+
205+
secret.deactivate()
206+
secret.activate()
207+
208+
for version in secret.list_versions(iterator=True):
209+
if version.id != secret.current_version.id:
210+
version.schedule_version_destruction()
211+
version.cancel_version_destruction()
212+
213+
214+
215+
216+
Modules
217+
-------
218+
219+
.. toctree::
220+
:maxdepth: 3
221+
:caption: Content:
222+
223+
pages/clients.rst
224+
pages/models.rst
225+
pages/exceptions.rst
226+
pages/adapters.rst
227+
pages/abstracts.rst
228+
229+
230+
231+
Indices and tables
232+
------------------
233+
234+
* :ref:`genindex`

‎docs/source/pages/abstracts.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Abstracts
2+
=========
3+
4+
Coming soon...

‎docs/source/pages/adapters.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Adapters
2+
========
3+
4+
Coming soon...

‎docs/source/pages/clients.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Client
2+
======
3+
4+
.. autoclass:: yc_lockbox.YandexLockboxClient
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
9+
.. autoclass:: yc_lockbox._auth.YandexAuthClient
10+
:members:
11+
:undoc-members:
12+
:show-inheritance:

‎docs/source/pages/exceptions.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Exceptions
2+
==========
3+
4+
Coming soon...

0 commit comments

Comments
 (0)