vercel-headers 0.6.0__tar.gz

vercel_headers-0.6.0/.gitignore

@@ -0,0 +1,128 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstallerhave
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# PDM
+pdm.lock
+.pdm.toml
+
+# Hatch
+.hatch/
+
+# pyright/mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# pyre
+.pyre/
+
+# pytype
+.pytype/
+
+# Caches
+__pypackages__/
+
+# Editor/project files
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Virtual environments
+.env
+.venv
+.venv.*
+env/
+venv/
+**/.env
+**/.venv
+**/.venv.*
+**/env/
+**/venv/
+ENV/
+env.bak/
+venv.bak/
+
+# dotenv anywhere
+**/.env
+**/.env.*
+**/*.env
+
+.claude

vercel_headers-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vercel_headers-0.6.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: vercel-headers
+Version: 0.6.0
+Summary: Request header helpers for Vercel Python applications
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Headers
+
+`vercel.headers` stores request headers for Vercel Function helpers and exposes
+IP address and geolocation helpers.
+
+Register request headers once per request:
+
+```python
+from vercel.headers import set_headers
+
+set_headers(request.headers)
+```
+
+OIDC and cache helpers read the same registered header context.

vercel_headers-0.6.0/README.md

@@ -0,0 +1,14 @@
+# Headers
+
+`vercel.headers` stores request headers for Vercel Function helpers and exposes
+IP address and geolocation helpers.
+
+Register request headers once per request:
+
+```python
+from vercel.headers import set_headers
+
+set_headers(request.headers)
+```
+
+OIDC and cache helpers read the same registered header context.

vercel_headers-0.6.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27.0,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vercel-headers"
+dynamic = ["version"]
+description = "Request header helpers for Vercel Python applications"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE", "LICENSE.*"]
+dependencies = []
+
+[tool.hatch.version]
+path = "vercel/headers/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/vercel/headers/**/*.py",
+    "/vercel/headers/py.typed",
+    "/README.md",
+    "/pyproject.toml",
+    "/LICENSE",
+]
+exclude = [
+    "/**/__pycache__",
+]
+
+[tool.hatch.build.targets.wheel]
+dev-mode-dirs = ["."]
+only-include = [
+    "/vercel/headers",
+]
+exclude = [
+    "/**/__pycache__",
+]

vercel_headers-0.6.0/vercel/headers/__init__.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import urllib.parse
+from collections.abc import Mapping
+from contextvars import ContextVar
+from typing import Protocol, TypedDict
+
+__all__ = [
+    "ip_address",
+    "geolocation",
+    "Geo",
+    "set_headers",
+    "get_headers",
+]
+
+
+_cv_headers: ContextVar[Mapping[str, str] | None] = ContextVar("vercel_headers", default=None)
+
+# Header constants (same as TS names)
+CITY_HEADER_NAME = "x-vercel-ip-city"
+COUNTRY_HEADER_NAME = "x-vercel-ip-country"
+IP_HEADER_NAME = "x-real-ip"
+LATITUDE_HEADER_NAME = "x-vercel-ip-latitude"
+LONGITUDE_HEADER_NAME = "x-vercel-ip-longitude"
+REGION_HEADER_NAME = "x-vercel-ip-country-region"
+POSTAL_CODE_HEADER_NAME = "x-vercel-ip-postal-code"
+REQUEST_ID_HEADER_NAME = "x-vercel-id"
+
+EMOJI_FLAG_UNICODE_STARTING_POSITION = 127397
+
+
+def set_headers(headers: Mapping[str, str] | None) -> None:
+    _cv_headers.set(headers)
+
+
+def get_headers() -> Mapping[str, str] | None:
+    return _cv_headers.get()
+
+
+class _HeadersLike(Protocol):
+    def get(self, name: str) -> str | None: ...
+
+
+class _RequestLike(Protocol):
+    headers: _HeadersLike
+
+
+class Geo(TypedDict, total=False):
+    city: str | None
+    country: str | None
+    flag: str | None
+    region: str | None
+    countryRegion: str | None
+    latitude: str | None
+    longitude: str | None
+    postalCode: str | None
+
+
+def _get_header(headers: _HeadersLike, key: str) -> str | None:
+    return headers.get(key)
+
+
+def _get_header_decode(req: _RequestLike, key: str) -> str | None:
+    raw = _get_header(req.headers, key)
+    return urllib.parse.unquote(raw) if raw is not None else None
+
+
+def _get_flag(country_code: str | None) -> str | None:
+    if not country_code or len(country_code) != 2 or not country_code.isalpha():
+        return None
+    return "".join(chr(EMOJI_FLAG_UNICODE_STARTING_POSITION + ord(c)) for c in country_code.upper())
+
+
+def ip_address(input: _RequestLike | _HeadersLike) -> str | None:
+    headers = input.headers if hasattr(input, "headers") else input
+    return _get_header(headers, IP_HEADER_NAME)
+
+
+def _region_from_request_id(request_id: str | None) -> str | None:
+    if request_id is None:
+        return "dev1"
+    return request_id.split(":")[0]
+
+
+def geolocation(request: _RequestLike) -> Geo:
+    headers = request.headers
+    return {
+        "city": _get_header_decode(request, CITY_HEADER_NAME),
+        "country": _get_header(headers, COUNTRY_HEADER_NAME),
+        "flag": _get_flag(_get_header(headers, COUNTRY_HEADER_NAME)),
+        "countryRegion": _get_header(headers, REGION_HEADER_NAME),
+        "region": _region_from_request_id(_get_header(headers, REQUEST_ID_HEADER_NAME)),
+        "latitude": _get_header(headers, LATITUDE_HEADER_NAME),
+        "longitude": _get_header(headers, LONGITUDE_HEADER_NAME),
+        "postalCode": _get_header(headers, POSTAL_CODE_HEADER_NAME),
+    }

vercel_headers-0.6.0/vercel/headers/version.py

@@ -0,0 +1 @@
+__version__ = "0.6.0"