commypanel 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CommyPanel contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,8 @@
1
+ include LICENSE README.md SECURITY.md
2
+ recursive-include src *.py py.typed
3
+ recursive-include tests *.py
4
+ include testdata/openapi.yaml
5
+ include scripts/sync-spec.sh
6
+ # The throwaway test-only certificates and keys are not shipped; the TLS tests skip without them.
7
+ prune tests/fixtures
8
+ global-exclude *.key *.pem
@@ -0,0 +1,126 @@
1
+ Metadata-Version: 2.4
2
+ Name: commypanel
3
+ Version: 0.1.0
4
+ Summary: A small, dependency-free client for the CommyPanel HTTP API.
5
+ Author: CommyPanel contributors
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/CommyPanel/commypanel-python
8
+ Project-URL: Source, https://github.com/CommyPanel/commypanel-python
9
+ Project-URL: Issues, https://github.com/CommyPanel/commypanel-python/issues
10
+ Project-URL: Panel, https://github.com/CommyPanel/panel
11
+ Keywords: commypanel,deploy,api-client,self-hosted
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: license-file
26
+
27
+ # commypanel-python
28
+
29
+ A small Python client for the HTTP API of a [CommyPanel](https://github.com/CommyPanel/panel) server: list
30
+ apps, start and follow deployments, start, stop and restart an app, read its logs and manage its
31
+ environment variables.
32
+
33
+ - **No dependencies.** Python standard library only, Python 3.9 or newer. Fully typed (`py.typed`).
34
+ - **Hard to misuse.** https only, no redirects, bounded retries and answers, and the token kept out of
35
+ errors and `repr`. See [Security](#security).
36
+ - **Matches the API.** `testdata/openapi.yaml` is a copy of the panel's API description, and a test fails
37
+ when the API gains a call this library does not have.
38
+
39
+ ```bash
40
+ pip install commypanel
41
+ ```
42
+
43
+ (Until the first release is on PyPI, install from a checkout: `pip install .`.)
44
+
45
+ ## Use
46
+
47
+ Create a token in the panel under **Settings > API tokens**. Give it only what it needs (for a deploy job:
48
+ `apps:deploy` and `apps:read`), limit it to one app, and let it expire.
49
+
50
+ ```python
51
+ import os
52
+ from commypanel import Client, is_conflict
53
+
54
+ client = Client("https://panel.example.com", os.environ["COMMY_TOKEN"])
55
+
56
+ try:
57
+ deployment = client.start_deployment("shop")
58
+ except Exception as err:
59
+ if is_conflict(err): # one is already running: err.deployment is that one
60
+ raise SystemExit("a deployment is already running: #%d" % err.deployment.number)
61
+ raise
62
+
63
+ deployment = client.wait_for_deployment(
64
+ "shop", deployment.number, poll=3, on_update=lambda d: print(d.status), timeout=600
65
+ )
66
+
67
+ if not deployment.succeeded:
68
+ raise SystemExit("the deployment ended as %s: %s" % (deployment.status, deployment.error))
69
+ ```
70
+
71
+ Errors from the panel are `commypanel.ApiError` (with `status`, `message`, `fields`, `deployment` and
72
+ `retry_after_seconds`); test them with `is_not_found`, `is_forbidden`, `is_conflict`, `is_unauthorized` and
73
+ `is_rate_limited`. Everything this library raises on purpose derives from `commypanel.CommyPanelError`.
74
+
75
+ | Method | API call | Ability |
76
+ |---|---|---|
77
+ | `token()` | `GET /token` | none |
78
+ | `list_apps()`, `get_app(slug)` | `GET /apps`, `GET /apps/{slug}` | `apps:read` |
79
+ | `list_deployments(slug, limit=None)`, `get_deployment(slug, number, with_log=False)` | `GET /apps/{slug}/deployments[/{n}]` | `apps:read` |
80
+ | `start_deployment(slug)`, `apply_changes(slug)` | `POST /apps/{slug}/deployments`, `/apply` | `apps:deploy` |
81
+ | `start_app(slug)`, `stop_app(slug)`, `restart_app(slug)` | `POST /apps/{slug}/start`, `/stop`, `/restart` | `apps:control` |
82
+ | `logs(slug, tail=None)` | `GET /apps/{slug}/logs` | `apps:logs` |
83
+ | `list_env(slug)`, `set_env(slug, key, value)`, `unset_env(slug, key)` | `GET`, `PUT`, `DELETE /apps/{slug}/env[/{key}]` | `apps:env` |
84
+ | `wait_for_deployment(slug, number, poll=3, on_update=None, timeout=None)` | polls `GET .../deployments/{n}` | `apps:read` |
85
+
86
+ Environment variable **values are write-only**: the API never returns them, so `list_env` gives names, and
87
+ `set_env` returns `(change, created)`.
88
+
89
+ ## Security
90
+
91
+ - **https only.** `Client` refuses any other address. `allow_http_loopback=True` allows plain http for
92
+ `localhost`, `127.0.0.1` and `::1` only, for development.
93
+ - **TLS is always verified**, including the host name. There is no option to skip it. For a panel with a
94
+ private CA pass `ca_cert_pem=` (a PEM string).
95
+ - **Redirects are never followed**, so the token cannot be handed to another address; a redirect raises
96
+ `RedirectError`.
97
+ - **The token stays out of sight.** It is only ever in the `Authorization` header: not in URLs, error
98
+ messages, `repr()`, `str()` or formatting, and a `Client` cannot be pickled.
99
+ - **Bounded.** A timeout (30 s per network operation), at most 2 retries (never for a write that may have
100
+ happened: only a 429, and gateway errors for reads), `Retry-After` capped at 30 s, answers capped at
101
+ 16 MiB.
102
+ - **Names are checked before any request**, so an app or variable name cannot change the path.
103
+ - **No dependencies and no install-time code**: nothing runs when you install it.
104
+
105
+ Report a security problem privately, as described in [SECURITY.md](SECURITY.md).
106
+
107
+ ## Compatibility
108
+
109
+ This library speaks API `v1` (`/api/v1`) of CommyPanel 0.10 and later. It needs Python 3.9 or newer. A
110
+ `Client` keeps no state between calls, so one can be shared between threads.
111
+
112
+ ## Development
113
+
114
+ ```bash
115
+ scripts/sync-spec.sh ../../commypanel # copy the API description from the panel repository
116
+ python3 -m unittest discover -s tests -v # no test dependencies
117
+ ```
118
+
119
+ `tests/fixtures/tls` holds throwaway test-only certificates (see the README there).
120
+
121
+ ## Publishing
122
+
123
+ Not yet published to PyPI. When it is, it will be from CI with PyPI trusted publishing (no long-lived
124
+ token) and signed attestations, set up as a deliberate step of its own.
125
+
126
+ MIT licensed.
@@ -0,0 +1,100 @@
1
+ # commypanel-python
2
+
3
+ A small Python client for the HTTP API of a [CommyPanel](https://github.com/CommyPanel/panel) server: list
4
+ apps, start and follow deployments, start, stop and restart an app, read its logs and manage its
5
+ environment variables.
6
+
7
+ - **No dependencies.** Python standard library only, Python 3.9 or newer. Fully typed (`py.typed`).
8
+ - **Hard to misuse.** https only, no redirects, bounded retries and answers, and the token kept out of
9
+ errors and `repr`. See [Security](#security).
10
+ - **Matches the API.** `testdata/openapi.yaml` is a copy of the panel's API description, and a test fails
11
+ when the API gains a call this library does not have.
12
+
13
+ ```bash
14
+ pip install commypanel
15
+ ```
16
+
17
+ (Until the first release is on PyPI, install from a checkout: `pip install .`.)
18
+
19
+ ## Use
20
+
21
+ Create a token in the panel under **Settings > API tokens**. Give it only what it needs (for a deploy job:
22
+ `apps:deploy` and `apps:read`), limit it to one app, and let it expire.
23
+
24
+ ```python
25
+ import os
26
+ from commypanel import Client, is_conflict
27
+
28
+ client = Client("https://panel.example.com", os.environ["COMMY_TOKEN"])
29
+
30
+ try:
31
+ deployment = client.start_deployment("shop")
32
+ except Exception as err:
33
+ if is_conflict(err): # one is already running: err.deployment is that one
34
+ raise SystemExit("a deployment is already running: #%d" % err.deployment.number)
35
+ raise
36
+
37
+ deployment = client.wait_for_deployment(
38
+ "shop", deployment.number, poll=3, on_update=lambda d: print(d.status), timeout=600
39
+ )
40
+
41
+ if not deployment.succeeded:
42
+ raise SystemExit("the deployment ended as %s: %s" % (deployment.status, deployment.error))
43
+ ```
44
+
45
+ Errors from the panel are `commypanel.ApiError` (with `status`, `message`, `fields`, `deployment` and
46
+ `retry_after_seconds`); test them with `is_not_found`, `is_forbidden`, `is_conflict`, `is_unauthorized` and
47
+ `is_rate_limited`. Everything this library raises on purpose derives from `commypanel.CommyPanelError`.
48
+
49
+ | Method | API call | Ability |
50
+ |---|---|---|
51
+ | `token()` | `GET /token` | none |
52
+ | `list_apps()`, `get_app(slug)` | `GET /apps`, `GET /apps/{slug}` | `apps:read` |
53
+ | `list_deployments(slug, limit=None)`, `get_deployment(slug, number, with_log=False)` | `GET /apps/{slug}/deployments[/{n}]` | `apps:read` |
54
+ | `start_deployment(slug)`, `apply_changes(slug)` | `POST /apps/{slug}/deployments`, `/apply` | `apps:deploy` |
55
+ | `start_app(slug)`, `stop_app(slug)`, `restart_app(slug)` | `POST /apps/{slug}/start`, `/stop`, `/restart` | `apps:control` |
56
+ | `logs(slug, tail=None)` | `GET /apps/{slug}/logs` | `apps:logs` |
57
+ | `list_env(slug)`, `set_env(slug, key, value)`, `unset_env(slug, key)` | `GET`, `PUT`, `DELETE /apps/{slug}/env[/{key}]` | `apps:env` |
58
+ | `wait_for_deployment(slug, number, poll=3, on_update=None, timeout=None)` | polls `GET .../deployments/{n}` | `apps:read` |
59
+
60
+ Environment variable **values are write-only**: the API never returns them, so `list_env` gives names, and
61
+ `set_env` returns `(change, created)`.
62
+
63
+ ## Security
64
+
65
+ - **https only.** `Client` refuses any other address. `allow_http_loopback=True` allows plain http for
66
+ `localhost`, `127.0.0.1` and `::1` only, for development.
67
+ - **TLS is always verified**, including the host name. There is no option to skip it. For a panel with a
68
+ private CA pass `ca_cert_pem=` (a PEM string).
69
+ - **Redirects are never followed**, so the token cannot be handed to another address; a redirect raises
70
+ `RedirectError`.
71
+ - **The token stays out of sight.** It is only ever in the `Authorization` header: not in URLs, error
72
+ messages, `repr()`, `str()` or formatting, and a `Client` cannot be pickled.
73
+ - **Bounded.** A timeout (30 s per network operation), at most 2 retries (never for a write that may have
74
+ happened: only a 429, and gateway errors for reads), `Retry-After` capped at 30 s, answers capped at
75
+ 16 MiB.
76
+ - **Names are checked before any request**, so an app or variable name cannot change the path.
77
+ - **No dependencies and no install-time code**: nothing runs when you install it.
78
+
79
+ Report a security problem privately, as described in [SECURITY.md](SECURITY.md).
80
+
81
+ ## Compatibility
82
+
83
+ This library speaks API `v1` (`/api/v1`) of CommyPanel 0.10 and later. It needs Python 3.9 or newer. A
84
+ `Client` keeps no state between calls, so one can be shared between threads.
85
+
86
+ ## Development
87
+
88
+ ```bash
89
+ scripts/sync-spec.sh ../../commypanel # copy the API description from the panel repository
90
+ python3 -m unittest discover -s tests -v # no test dependencies
91
+ ```
92
+
93
+ `tests/fixtures/tls` holds throwaway test-only certificates (see the README there).
94
+
95
+ ## Publishing
96
+
97
+ Not yet published to PyPI. When it is, it will be from CI with PyPI trusted publishing (no long-lived
98
+ token) and signed attestations, set up as a deliberate step of its own.
99
+
100
+ MIT licensed.
@@ -0,0 +1,7 @@
1
+ # Security
2
+
3
+ If you find a security problem in this library, please do not open a public issue. Report it privately
4
+ through GitHub's "Report a vulnerability" button on this repository (Security tab). You will get an
5
+ answer, and a fix for a confirmed problem is released before the details are made public.
6
+
7
+ Problems in the CommyPanel server itself belong in the panel repository's own SECURITY.md.
@@ -0,0 +1,45 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "commypanel"
7
+ dynamic = ["version"]
8
+ description = "A small, dependency-free client for the CommyPanel HTTP API."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "CommyPanel contributors" }]
14
+ keywords = ["commypanel", "deploy", "api-client", "self-hosted"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.9",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Typing :: Typed",
26
+ ]
27
+ dependencies = []
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/CommyPanel/commypanel-python"
31
+ Source = "https://github.com/CommyPanel/commypanel-python"
32
+ Issues = "https://github.com/CommyPanel/commypanel-python/issues"
33
+ Panel = "https://github.com/CommyPanel/panel"
34
+
35
+ [tool.setuptools]
36
+ package-dir = { "" = "src" }
37
+
38
+ [tool.setuptools.packages.find]
39
+ where = ["src"]
40
+
41
+ [tool.setuptools.package-data]
42
+ commypanel = ["py.typed"]
43
+
44
+ [tool.setuptools.dynamic]
45
+ version = { attr = "commypanel.__version__" }
@@ -0,0 +1,7 @@
1
+ #!/usr/bin/env bash
2
+ # Copies the API description from the panel repository, so the contract test checks this library
3
+ # against the version of the API it claims to speak. Usage: scripts/sync-spec.sh [path-to-panel-repo]
4
+ set -euo pipefail
5
+ panel="${1:-../../commypanel}"
6
+ cp "$panel/docs/openapi.yaml" "$(dirname "$0")/../testdata/openapi.yaml"
7
+ echo "Copied $panel/docs/openapi.yaml"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,78 @@
1
+ """A small client for the HTTP API of a CommyPanel server.
2
+
3
+ List apps, start and follow deployments, start, stop and restart an app, read its logs and manage its
4
+ environment variables. Standard library only, and built to be hard to misuse:
5
+
6
+ * the panel address must be https (plain http only for localhost, and only when asked for);
7
+ * redirects are never followed, so the token cannot be sent to another host;
8
+ * the token is kept out of errors, ``repr`` and formatting;
9
+ * calls have a timeout, bounded retries and a limit on the size of an answer;
10
+ * environment variable values can only be written, because the API never returns them.
11
+
12
+ Create a token in the panel under Settings > API tokens, give it only the abilities it needs, limit it to one
13
+ app and let it expire::
14
+
15
+ import os
16
+ from commypanel import Client
17
+
18
+ client = Client("https://panel.example.com", os.environ["COMMY_TOKEN"])
19
+ deployment = client.start_deployment("shop")
20
+ deployment = client.wait_for_deployment("shop", deployment.number)
21
+ """
22
+
23
+ from ._client import Client, __version__
24
+ from ._errors import (
25
+ ApiError,
26
+ CommyPanelError,
27
+ InsecureURLError,
28
+ InvalidInputError,
29
+ InvalidTokenError,
30
+ InvalidURLError,
31
+ RedirectError,
32
+ ResponseTooLargeError,
33
+ TransportError,
34
+ WaitTimeoutError,
35
+ is_conflict,
36
+ is_forbidden,
37
+ is_not_found,
38
+ is_rate_limited,
39
+ is_unauthorized,
40
+ )
41
+ from ._types import (
42
+ Ability,
43
+ App,
44
+ Deployment,
45
+ DeployStrategy,
46
+ EnvChange,
47
+ EnvKeys,
48
+ Logs,
49
+ Token,
50
+ )
51
+
52
+ __all__ = [
53
+ "Ability",
54
+ "ApiError",
55
+ "App",
56
+ "Client",
57
+ "CommyPanelError",
58
+ "DeployStrategy",
59
+ "Deployment",
60
+ "EnvChange",
61
+ "EnvKeys",
62
+ "InsecureURLError",
63
+ "InvalidInputError",
64
+ "InvalidTokenError",
65
+ "InvalidURLError",
66
+ "Logs",
67
+ "RedirectError",
68
+ "ResponseTooLargeError",
69
+ "Token",
70
+ "TransportError",
71
+ "WaitTimeoutError",
72
+ "__version__",
73
+ "is_conflict",
74
+ "is_forbidden",
75
+ "is_not_found",
76
+ "is_rate_limited",
77
+ "is_unauthorized",
78
+ ]