jupyterhub_usage_quotas 0.0.1__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,262 @@
1
+ ### Linux template
2
+ *~
3
+
4
+ # temporary files which can be created if a process still has a handle open of a deleted file
5
+ .fuse_hidden*
6
+
7
+ # KDE directory preferences
8
+ .directory
9
+
10
+ # Linux trash folder which might appear on any partition or disk
11
+ .Trash-*
12
+
13
+ # .nfs files are created when an open file is removed but is still being accessed
14
+ .nfs*
15
+
16
+ ### Windows template
17
+ # Windows thumbnail cache files
18
+ Thumbs.db
19
+ Thumbs.db:encryptable
20
+ ehthumbs.db
21
+ ehthumbs_vista.db
22
+
23
+ # Dump file
24
+ *.stackdump
25
+
26
+ # Folder config file
27
+ [Dd]esktop.ini
28
+
29
+ # Recycle Bin used on file shares
30
+ $RECYCLE.BIN/
31
+
32
+ # Windows Installer files
33
+ *.cab
34
+ *.msi
35
+ *.msix
36
+ *.msm
37
+ *.msp
38
+
39
+ # Windows shortcuts
40
+ *.lnk
41
+
42
+ ### JupyterNotebooks template
43
+ # gitignore template for Jupyter Notebooks
44
+ # website: http://jupyter.org/
45
+
46
+ .ipynb_checkpoints
47
+ */.ipynb_checkpoints/*
48
+
49
+ # IPython
50
+ profile_default/
51
+ ipython_config.py
52
+
53
+ # Remove previous ipynb_checkpoints
54
+ # git rm -r .ipynb_checkpoints/
55
+
56
+ ### macOS template
57
+ # General
58
+ .DS_Store
59
+ .AppleDouble
60
+ .LSOverride
61
+
62
+ # Icon must end with two \r
63
+ Icon
64
+
65
+ # Thumbnails
66
+ ._*
67
+
68
+ # Files that might appear in the root of a volume
69
+ .DocumentRevisions-V100
70
+ .fseventsd
71
+ .Spotlight-V100
72
+ .TemporaryItems
73
+ .Trashes
74
+ .VolumeIcon.icns
75
+ .com.apple.timemachine.donotpresent
76
+
77
+ # Directories potentially created on remote AFP share
78
+ .AppleDB
79
+ .AppleDesktop
80
+ Network Trash Folder
81
+ Temporary Items
82
+ .apdisk
83
+
84
+ ### Python template
85
+ # Byte-compiled / optimized / DLL files
86
+ __pycache__/
87
+ *.py[cod]
88
+ *$py.class
89
+
90
+ # C extensions
91
+ *.so
92
+
93
+ # Distribution / packaging
94
+ .Python
95
+ build/
96
+ develop-eggs/
97
+ dist/
98
+ downloads/
99
+ eggs/
100
+ .eggs/
101
+ lib/
102
+ lib64/
103
+ parts/
104
+ sdist/
105
+ var/
106
+ wheels/
107
+ share/python-wheels/
108
+ *.egg-info/
109
+ .installed.cfg
110
+ *.egg
111
+ MANIFEST
112
+
113
+ # PyInstaller
114
+ # Usually these files are written by a python script from a template
115
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
116
+ *.manifest
117
+ *.spec
118
+
119
+ # Installer logs
120
+ pip-log.txt
121
+ pip-delete-this-directory.txt
122
+
123
+ # Unit test / coverage reports
124
+ htmlcov/
125
+ .tox/
126
+ .nox/
127
+ .coverage
128
+ .coverage.*
129
+ .cache
130
+ nosetests.xml
131
+ coverage.xml
132
+ *.cover
133
+ *.py,cover
134
+ .hypothesis/
135
+ .pytest_cache/
136
+ cover/
137
+
138
+ # Translations
139
+ *.mo
140
+ *.pot
141
+
142
+ # Django stuff:
143
+ *.log
144
+ local_settings.py
145
+ db.sqlite3
146
+ db.sqlite3-journal
147
+
148
+ # Flask stuff:
149
+ instance/
150
+ .webassets-cache
151
+
152
+ # Scrapy stuff:
153
+ .scrapy
154
+
155
+ # Sphinx documentation
156
+ docs/_build/
157
+
158
+ # PyBuilder
159
+ .pybuilder/
160
+ target/
161
+
162
+ # Jupyter Notebook
163
+
164
+ # IPython
165
+
166
+ # pyenv
167
+ # For a library or package, you might want to ignore these files since the code is
168
+ # intended to run in multiple environments; otherwise, check them in:
169
+ # .python-version
170
+
171
+ # pipenv
172
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
173
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
174
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
175
+ # install all needed dependencies.
176
+ #Pipfile.lock
177
+
178
+ # poetry
179
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
180
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
181
+ # commonly ignored for libraries.
182
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
183
+ #poetry.lock
184
+
185
+ # pdm
186
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
187
+ #pdm.lock
188
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
189
+ # in version control.
190
+ # https://pdm.fming.dev/#use-with-ide
191
+ .pdm.toml
192
+
193
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
194
+ __pypackages__/
195
+
196
+ # Celery stuff
197
+ celerybeat-schedule
198
+ celerybeat.pid
199
+
200
+ # SageMath parsed files
201
+ *.sage.py
202
+
203
+ # Environments
204
+ .env
205
+ .venv
206
+ env/
207
+ venv/
208
+ ENV/
209
+ env.bak/
210
+ venv.bak/
211
+
212
+ # Spyder project settings
213
+ .spyderproject
214
+ .spyproject
215
+
216
+ # Rope project settings
217
+ .ropeproject
218
+
219
+ # mkdocs documentation
220
+ /site
221
+
222
+ # mypy
223
+ .mypy_cache/
224
+ .dmypy.json
225
+ dmypy.json
226
+
227
+ # Pyre type checker
228
+ .pyre/
229
+
230
+ # pytype static type analyzer
231
+ .pytype/
232
+
233
+ # Cython debug symbols
234
+ cython_debug/
235
+
236
+ # PyCharm
237
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
238
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
239
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
240
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
241
+ #.idea/
242
+ .vscode/
243
+
244
+ # Docs
245
+ **/_build/**
246
+
247
+ # local dev artifacts
248
+ # minikube
249
+ bin/
250
+ lib64
251
+ minikube-linux-amd64
252
+ node_modules/
253
+ package.json
254
+ package-lock.json
255
+ pyvenv.cfg
256
+ share/
257
+ pip-selfcheck.json
258
+
259
+ # JupyterHub
260
+ jupyterhub-proxy.pid
261
+ jupyterhub.sqlite
262
+ jupyterhub_cookie_secret
@@ -0,0 +1,30 @@
1
+ # License
2
+
3
+ Copyright (2026) 2i2c
4
+
5
+ BSD-3-Clause
6
+
7
+ Redistribution and use in source and binary forms, with or without modification,
8
+ are permitted provided that the following conditions are met:
9
+
10
+ 1. Redistributions of source code must retain the above copyright notice, this
11
+ list of conditions and the following disclaimer.
12
+
13
+ 1. Redistributions in binary form must reproduce the above copyright notice,
14
+ this list of conditions and the following disclaimer in the documentation and/or
15
+ other materials provided with the distribution.
16
+
17
+ 1. Neither the name of the copyright holder nor the names of its contributors
18
+ may be used to endorse or promote products derived from this software without
19
+ specific prior written permission.
20
+
21
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
22
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
25
+ ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
28
+ ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,53 @@
1
+ Metadata-Version: 2.4
2
+ Name: jupyterhub_usage_quotas
3
+ Version: 0.0.1
4
+ Summary: Enforce compute usage quotas at Jupyter server launch time to proactively manage resource consumption.
5
+ Project-URL: Homepage, https://github.com/2i2c-org/jupyterhub-usage-quotas
6
+ Project-URL: Source Code, https://github.com/2i2c-org/jupyterhub-usage-quotas
7
+ Project-URL: Bug Tracker, https://github.com/2i2c-org/jupyterhub-usage-quotas/issues
8
+ Project-URL: Documentation, https://jupyterhub-usage-quotas.readthedocs.io/en/latest/
9
+ Author-email: jnywong <jnywong.pro@gmail.com>
10
+ License-Expression: BSD-3-Clause
11
+ License-File: LICENSE.md
12
+ Keywords: jupyterhub,kubernetes,prometheus,python
13
+ Classifier: Development Status :: 2 - Pre-Alpha
14
+ Classifier: Intended Audience :: System Administrators
15
+ Classifier: License :: OSI Approved :: BSD License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Typing :: Typed
19
+ Requires-Dist: jsonschema>=4.26.0
20
+ Requires-Dist: requests>=2.32.0
21
+ Requires-Dist: traitlets>=5.14.0
22
+ Provides-Extra: dev
23
+ Requires-Dist: jupyterhub-kubespawner>=7.0.0; extra == 'dev'
24
+ Requires-Dist: jupyterhub>=5.0.0; extra == 'dev'
25
+ Description-Content-Type: text/markdown
26
+
27
+ # JupyterHub Usage Quotas
28
+
29
+ This library implements compute usage quotas for Jupyter servers at server startup-time to manage resource consumption across shared infrastructure managed by [Zero to JupyterHub with Kubernetes](https://z2jh.jupyter.org/en/stable/) deployments.
30
+
31
+ ## Features
32
+
33
+ - Metric based accounting for compute usage with Prometheus
34
+ - Flexible and declarative usage policies, such as quota sizes and quota time windows
35
+ - Server startup-time enforcement
36
+
37
+ ## Installation
38
+
39
+ _`pip install` instructions to follow_
40
+
41
+ For local development, see the [development guide](./DEVELOPMENT.md)
42
+
43
+ ## Documentation
44
+
45
+ Documentation can be found at [https://jupyterhub-usage-quotas.readthedocs.io/en/latest/](https://jupyterhub-usage-quotas.readthedocs.io/en/latest/)
46
+
47
+ ## Contributing
48
+
49
+ See the guidance in [CONTRIBUTING](CONTRIBUTING.md)
50
+
51
+ ## License
52
+
53
+ This project is licensed under the [BSD 3-Clause License](LICENSE.md).
@@ -0,0 +1,27 @@
1
+ # JupyterHub Usage Quotas
2
+
3
+ This library implements compute usage quotas for Jupyter servers at server startup-time to manage resource consumption across shared infrastructure managed by [Zero to JupyterHub with Kubernetes](https://z2jh.jupyter.org/en/stable/) deployments.
4
+
5
+ ## Features
6
+
7
+ - Metric based accounting for compute usage with Prometheus
8
+ - Flexible and declarative usage policies, such as quota sizes and quota time windows
9
+ - Server startup-time enforcement
10
+
11
+ ## Installation
12
+
13
+ _`pip install` instructions to follow_
14
+
15
+ For local development, see the [development guide](./DEVELOPMENT.md)
16
+
17
+ ## Documentation
18
+
19
+ Documentation can be found at [https://jupyterhub-usage-quotas.readthedocs.io/en/latest/](https://jupyterhub-usage-quotas.readthedocs.io/en/latest/)
20
+
21
+ ## Contributing
22
+
23
+ See the guidance in [CONTRIBUTING](CONTRIBUTING.md)
24
+
25
+ ## License
26
+
27
+ This project is licensed under the [BSD 3-Clause License](LICENSE.md).
@@ -0,0 +1,216 @@
1
+ ################################################################################
2
+ # Build Configuration
3
+ ################################################################################
4
+
5
+ [build-system]
6
+ build-backend = "hatchling.build"
7
+ requires = ["hatchling", "hatch-vcs"]
8
+
9
+ ################################################################################
10
+ # Project Configuration
11
+ ################################################################################
12
+
13
+ [project]
14
+ name = "jupyterhub_usage_quotas"
15
+
16
+ dynamic = ["version"]
17
+
18
+ description = "Enforce compute usage quotas at Jupyter server launch time to proactively manage resource consumption."
19
+ authors = [
20
+ { name = "jnywong", email = "jnywong.pro@gmail.com" },
21
+ ]
22
+ license = "BSD-3-Clause"
23
+ readme = {"file" = "README.md", "content-type" = "text/markdown"}
24
+ # Please consult https://pypi.org/classifiers/ for a full list.
25
+ classifiers = [
26
+ "Development Status :: 2 - Pre-Alpha",
27
+ "Intended Audience :: System Administrators",
28
+ "License :: OSI Approved :: BSD License",
29
+ "Operating System :: OS Independent",
30
+ "Programming Language :: Python :: 3 :: Only",
31
+ "Typing :: Typed",
32
+ ]
33
+
34
+ keywords = ["jupyterhub", "prometheus", "kubernetes", "python"]
35
+
36
+ # Package dependencies
37
+ dependencies = [
38
+ "jsonschema>=4.26.0",
39
+ "traitlets>=5.14.0",
40
+ "requests>=2.32.0",
41
+ ]
42
+
43
+ [project.urls]
44
+ "Homepage" = "https://github.com/2i2c-org/jupyterhub-usage-quotas"
45
+ "Source Code" = "https://github.com/2i2c-org/jupyterhub-usage-quotas"
46
+ "Bug Tracker" = "https://github.com/2i2c-org/jupyterhub-usage-quotas/issues"
47
+ "Documentation" = "https://jupyterhub-usage-quotas.readthedocs.io/en/latest/"
48
+
49
+ [project.scripts]
50
+ jupyterhub_usage_quotas = "jupyterhub_usage_quotas.app:main"
51
+
52
+ [project.optional-dependencies]
53
+ dev = [
54
+ "jupyterhub>=5.0.0",
55
+ "jupyterhub-kubespawner>=7.0.0",
56
+ ]
57
+
58
+ ################################################################################
59
+ # Tool Configuration
60
+ ################################################################################
61
+
62
+ # Exclude files outside package
63
+ [tool.hatch.build]
64
+ only-packages = true
65
+
66
+ [tool.hatch.build.targets.wheel]
67
+ packages = ["src/jupyterhub_usage_quotas"]
68
+
69
+ # [tool.hatch.build.hooks.vcs]
70
+ version-file = "src/jupyterhub_usage_quotas/_version.py"
71
+
72
+ [tool.hatch.version]
73
+ source = "vcs"
74
+
75
+ [tool.hatch.version.raw-options]
76
+ version_scheme = "no-guess-dev"
77
+
78
+ # The default isort output conflicts with black autoformatting.
79
+ # Tell isort to behave nicely with black
80
+ # See https://pycqa.github.io/isort/docs/configuration/black_compatibility.html
81
+ # for more information.
82
+ [tool.isort]
83
+ profile = "black"
84
+
85
+ [tool.pydoclint]
86
+ style = "google"
87
+ arg-type-hints-in-docstring = false
88
+ check-return-types = false
89
+ check-yield-types = false
90
+ exclude = "_version.py"
91
+
92
+ [tool.pytest.ini_options]
93
+ testpaths = ["tests"]
94
+ markers = ["raises"]
95
+
96
+ [tool.coverage.paths]
97
+ source = [
98
+ "src/jupyterhub_usage_quotas",
99
+ ]
100
+
101
+ [tool.coverage.run]
102
+ branch = true
103
+ parallel = true
104
+ omit = [
105
+ "src/jupyterhub_usage_quotas/_version.py",
106
+ ]
107
+
108
+ [tool.coverage.report]
109
+ exclude_lines = ["pragma: no cover"]
110
+ precision = 2
111
+
112
+ ################################################################################
113
+ # Hatch Environments
114
+ ################################################################################
115
+
116
+ [tool.hatch.envs.default]
117
+ python="3.14"
118
+ installer="pip"
119
+ post-install-commands = [
120
+ "python -m pip install --upgrade pip"
121
+ ]
122
+
123
+ [tool.hatch.envs.py313]
124
+ python = "3.13"
125
+
126
+ [tool.hatch.envs.py312]
127
+ python = "3.12"
128
+
129
+ [tool.hatch.envs.dev]
130
+ inherits = ["default"]
131
+ description = """
132
+ Environment for local development.
133
+ """
134
+ features = ["dev"]
135
+ dependencies = [
136
+ "ipython",
137
+ "pre-commit",
138
+ ]
139
+
140
+ [tool.hatch.envs.install]
141
+ description = """Test the installation the package."""
142
+ dependencies = [
143
+ "pip",
144
+ "twine",
145
+ ]
146
+ detached = true
147
+ builder = true
148
+
149
+ [tool.hatch.envs.install.scripts]
150
+ check = [
151
+ "pip check",
152
+ "hatch build {args:--clean}",
153
+ "twine check dist/*",
154
+ ]
155
+
156
+ [tool.hatch.envs.test]
157
+ description = """
158
+ Run test suite
159
+ """
160
+ dependencies = [
161
+ "pytest",
162
+ "pytest-cov",
163
+ "pytest-raises",
164
+ "pytest-randomly",
165
+ "pytest-xdist",
166
+ ]
167
+
168
+ [[tool.hatch.envs.test.matrix]]
169
+ python = ["3.12", "3.13", "3.14"]
170
+
171
+ [tool.hatch.envs.test.scripts]
172
+ run = "pytest {args:--cov=src/jupyterhub_usage_quotas --cov-report=term-missing --cov-report=xml}"
173
+
174
+ [tool.hatch.envs.style]
175
+ description = """Check the style of the codebase."""
176
+ dependencies = [
177
+ "pydoclint",
178
+ ]
179
+ detached = true
180
+
181
+ [tool.hatch.envs.style.scripts]
182
+ docstrings = "pydoclint"
183
+ check = ["docstrings"]
184
+
185
+ [tool.hatch.envs.audit]
186
+ description = """Check dependencies for security vulnerabilities."""
187
+ extra-dependencies = [
188
+ "pip-audit",
189
+ ]
190
+
191
+ [tool.hatch.envs.audit.scripts]
192
+ check = ["pip-audit --skip-editable"]
193
+
194
+ [tool.hatch.envs.types]
195
+ description = """Check the static types of the codebase."""
196
+ dependencies = [
197
+ "mypy",
198
+ ]
199
+
200
+ [tool.mypy]
201
+ ignore_missing_imports = true
202
+
203
+ [tool.hatch.envs.types.scripts]
204
+ check = "mypy src/jupyterhub_usage_quotas"
205
+
206
+ [tool.hatch.envs.docs]
207
+ description = """Build or serve the documentation."""
208
+ python = "3.14"
209
+ dependencies = [
210
+ "mystmd",
211
+ ]
212
+ detached = true
213
+
214
+ [tool.hatch.envs.docs.scripts]
215
+ build = ["env -C docs -- myst build --html"]
216
+ serve = ["env -C docs -- myst start"]
@@ -0,0 +1,26 @@
1
+ import aiohttp
2
+ from aiohttp import web
3
+ from yarl import URL
4
+
5
+
6
+ class PrometheusClient:
7
+ def __init__(self, prometheus_url: str):
8
+ self.prometheus_url = URL(prometheus_url)
9
+ self.session = None
10
+
11
+ async def _get_session(self) -> aiohttp.ClientSession:
12
+ if self.session is None or self.session.closed:
13
+ self.session = aiohttp.ClientSession()
14
+ return self.session
15
+
16
+ async def query(self, promql: str) -> dict:
17
+ session = await self._get_session()
18
+ api_url = self.prometheus_url.with_path("api/v1/query")
19
+ params = {"query": promql}
20
+ try:
21
+ async with session.get(api_url, params=params) as response:
22
+ response.raise_for_status()
23
+ data = await response.json()
24
+ return data
25
+ except aiohttp.ClientError as e:
26
+ raise web.Response(status=500, text=f"Error querying prometheus: {e}")
@@ -0,0 +1,194 @@
1
+ """
2
+ Traitlets based configuration for jupyterhub_usage_quotas
3
+ """
4
+
5
+ import copy
6
+ import typing
7
+
8
+ import jsonschema
9
+ from traitlets import Bool, Dict, Integer, List, TraitError, Unicode, validate
10
+ from traitlets.config import Configurable
11
+
12
+ Schema = typing.Dict[str, typing.Any]
13
+
14
+ # JSON schema for the scope backup policy for usage quotas
15
+ policy_schema_backup: Schema = {
16
+ "type": "object",
17
+ "properties": {
18
+ "resource": {"type": "string"},
19
+ "limit": {
20
+ "type": "object",
21
+ "properties": {
22
+ "value": {"type": "number"},
23
+ "unit": {"enum": ["GiB-hours", "CPU-hours"]},
24
+ },
25
+ },
26
+ "window": {"type": "number"},
27
+ },
28
+ "required": ["resource", "limit", "window"],
29
+ "additionalProperties": False,
30
+ }
31
+
32
+ # JSON schema for the usage quota policy
33
+ policy_schema = copy.deepcopy(policy_schema_backup)
34
+ policy_schema["properties"].update(
35
+ {
36
+ "scope": {
37
+ "type": "object",
38
+ "properties": {"group": {"type": "array", "items": {"type": "string"}}},
39
+ "additionalProperties": False,
40
+ }
41
+ }
42
+ )
43
+ policy_schema["required"].append("scope")
44
+
45
+
46
+ class UsageQuotaConfig(Configurable):
47
+ """
48
+ Configure application settings for the JupyterHub usage quotas system.
49
+ """
50
+
51
+ # System config
52
+
53
+ prometheus_url = Unicode(
54
+ "http://localhost:9090",
55
+ help="The url of the Prometheus server, usually of the form 'http://<k8s-service-name>.<k8s-namespace>.svc.cluster.local' in a Kubernetes cluster. Defaults to 'http://localhost:9090' for local development if left blank.",
56
+ ).tag(config=True)
57
+
58
+ prometheus_usage_metrics = Dict(
59
+ help="""
60
+ Dict of Prometheus metrics to track usage. Must define at least one of:
61
+ - 'memory': PromQL expression
62
+ - 'cpu': PromQL expression
63
+ For example:
64
+ prometheus_usage_metrics = {
65
+ "memory": "kube_pod_container_resource_requests{resource='memory'}",
66
+ "cpu" : "kube_pod_container_resource_requests{resource='cpu'}"
67
+ }
68
+ """,
69
+ ).tag(config=True)
70
+
71
+ @validate("prometheus_usage_metrics")
72
+ def _validate_prometheus_usage_metrics(self, proposal):
73
+ """
74
+ Validate that memory or cpu usage metrics are defined.
75
+ """
76
+ metrics = proposal["value"]
77
+ if not isinstance(metrics, dict):
78
+ raise TraitError(
79
+ f"Prometheus usage metrics {metrics} must be a dict, got {type(metrics)}"
80
+ )
81
+
82
+ for metric_def in metrics:
83
+ if not metric_def in {"memory", "cpu"}:
84
+ raise TraitError(
85
+ f"Prometheus usage metrics {metrics} must define at least one of 'memory' or 'cpu' keys. Got keys: {list(metrics.keys())}"
86
+ )
87
+
88
+ return metrics
89
+
90
+ prometheus_scrape_interval = Integer(
91
+ 15, help="Scrape interval of Prometheus sample collection (seconds)."
92
+ ).tag(config=True)
93
+
94
+ bucket_size_seconds = Integer(
95
+ 300, help="Granularity of usage buckets (seconds)."
96
+ ).tag(config=True)
97
+
98
+ sample_interval_seconds = Integer(
99
+ 30, help="How often usage is sampled by the quota system (seconds)."
100
+ ).tag(config=True)
101
+
102
+ scope_backup_strategy = Dict(
103
+ per_key_traits={
104
+ "empty": Dict(),
105
+ "intersection": Unicode(),
106
+ },
107
+ default_value={"intersection": "min"},
108
+ help="""
109
+ Set a backup strategy to resolve quotas in the case where the scope of the quota policies are applied to an empty set, or an intersection, i.e. define a default when a user has no or multiple quotas applied.
110
+
111
+ In the case where no quota is applied ('empty'), we can supply a default quota policy or leave this as None for unlimited quotas; and where multiple quotas are applied, we can apply either the `min` or `max`.
112
+
113
+ For example, 'Apply a default memory quota of 500 GiB-hours over a rolling 7 day window for users with no groups, and apply the maximum quota available for users with multiple groups.' is expressed as:
114
+
115
+ {
116
+ "empty": {
117
+ "resource": "memory",
118
+ "limit": {
119
+ "value": 500,
120
+ "unit": "GiB-hours"
121
+ },
122
+ "window": 7,
123
+ },
124
+ "intersection": "max"
125
+ }
126
+ """,
127
+ ).tag(config=True)
128
+
129
+ @validate("scope_backup_strategy")
130
+ def _validate_scope_backup_strategy(self, proposal):
131
+ """
132
+ Validate that the scope backup strategy is defined.
133
+ """
134
+ strategy = proposal["value"]
135
+ required = set(["intersection"])
136
+ allowed = required | set(["empty"])
137
+ if required - set(strategy.keys()):
138
+ raise TraitError(
139
+ f"Must define backup strategy for 'intersection' scope. Got keys: {list(strategy.keys())}"
140
+ )
141
+ extra = set(strategy.keys()) - allowed
142
+ if extra:
143
+ raise TraitError(f"Unexpected keys: {extra}")
144
+ if "empty" in strategy.keys():
145
+ try:
146
+ jsonschema.validate(strategy["empty"], policy_schema_backup)
147
+ except jsonschema.ValidationError as e:
148
+ raise TraitError(e)
149
+ if not strategy["intersection"] in {"min", "max"}:
150
+ raise TraitError(
151
+ f"Backup strategy for 'intersection' scope must be either 'min' or 'max'. Got value: {strategy['intersection']}"
152
+ )
153
+
154
+ return strategy
155
+
156
+ failover_open = Bool(
157
+ True,
158
+ help="In the case where the quota system fails, set to True to default to a fail-open (allow all server launches) system or set to False to a fail-closed (deny all server launches) system.",
159
+ ).tag(config=True)
160
+
161
+ # Policy config
162
+
163
+ policy = List(
164
+ Dict(),
165
+ help="""
166
+ List usage quota policies, including resource, limits, rolling window period and policy scope.
167
+
168
+ For example: '5,000 GiB-hours over 30 days for group A', is expressed as
169
+
170
+ c.UsageQuotaConfig.policy = [{
171
+ "resource": "memory",
172
+ "limit": {
173
+ "value": 5000,
174
+ "unit": "GiB-hours",
175
+ }
176
+ "window": 30, # days
177
+ "scope": {
178
+ "group": ["A"]
179
+ }
180
+ }]
181
+ """,
182
+ ).tag(config=True)
183
+
184
+ @validate("policy")
185
+ def _validate_policy(self, proposal):
186
+ policies = proposal["value"]
187
+ for i, policy_def in enumerate(policies):
188
+ if not isinstance(policy_def, dict):
189
+ raise TraitError(f"Entry {i} must be a dict, got {type(policy_def)}")
190
+ try:
191
+ jsonschema.validate(policy_def, policy_schema)
192
+ except jsonschema.ValidationError as e:
193
+ raise TraitError(e)
194
+ return policies
@@ -0,0 +1,23 @@
1
+ import re
2
+
3
+ from jupyterhub_usage_quotas.client import PrometheusClient
4
+ from jupyterhub_usage_quotas.config import UsageQuotaConfig
5
+
6
+
7
+ class UsageQuotaManager(UsageQuotaConfig):
8
+
9
+ def __init__(self, **kwargs):
10
+ super().__init__(**kwargs)
11
+ self.prometheus_client = PrometheusClient(self.prometheus_url)
12
+
13
+ async def enforce(self, user):
14
+ usage_metric = self.prometheus_usage_metrics["memory"]
15
+ pattern = r"(\{.*?)(\})"
16
+ repl = rf"\1, pod='jupyter-{user}'\2"
17
+ promql = re.sub(pattern, repl, usage_metric)
18
+ data = await self.prometheus_client.query(promql)
19
+ print(f"{data=}")
20
+
21
+ # TODO: apply quota logic
22
+
23
+ return True
@@ -0,0 +1,2 @@
1
+ # PEP-561 Support File.
2
+ # "Package maintainers who wish to support type checking of their code MUST add a marker file named py.typed to their package supporting typing".
File without changes
@@ -0,0 +1,7 @@
1
+ # Source - https://stackoverflow.com/a/78063247
2
+ # Posted by defaultUsernameN
3
+ # Retrieved 2026-01-30, License - CC BY-SA 4.0
4
+
5
+
6
+ def test_dummy():
7
+ pass