fastapi-ipware 0.2.0__tar.gz → 1.0.0__tar.gz

{fastapi_ipware-0.2.0 → fastapi_ipware-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-ipware
-Version: 0.2.0
+Version: 1.0.0
 Summary: FastAPI/Starlette-native wrapper for python-ipware to get client IP addresses
 Keywords: fastapi,starlette,ipware,ip-address,client-ip,proxy,x-forwarded-for
 Author: Michael Bianco
@@ -45,10 +45,6 @@ uv add fastapi-ipware
 
 ## Quick Start
 
-`trusted` is true only when the request came through the proxies configured with `proxy_count` or `proxy_list`.
-
-`proxy_count=N` returns the address just left of the N rightmost proxies, instead of the first public address, and rejects a shorter chain. `X-Forwarded-For: 203.0.113.10, 10.0.0.1, 10.0.0.2` returns `203.0.113.10` with no `proxy_count`, and `10.0.0.1` with `proxy_count=1`.
-
 ### Using FastAPI Dependency Injection
 
 ```python
@@ -62,6 +58,8 @@ ipware = FastAPIIpWare()
 
 @app.get("/")
 async def get_ip(client: Annotated[ClientIpResult, Depends(ipware)]):
+    # trusted is true only when the request came through the proxies
+    # configured with proxy_count or proxy_list
     ip, trusted = client
     return {
         "ip": str(ip) if ip else None,
@@ -150,6 +148,10 @@ Validate that requests pass through the expected number of proxies:
 
 ```python
 # Expect exactly 1 proxy (e.g., AWS ALB).
+# proxy_count=N returns the address just left of the N rightmost proxies,
+# instead of the first public address, and rejects a shorter chain.
+# X-Forwarded-For: 203.0.113.10, 10.0.0.1, 10.0.0.2 returns 203.0.113.10
+# with no proxy_count, and 10.0.0.1 with proxy_count=1.
 # default_strict applies to Depends(ipware), dependency(), and IpWareMiddleware.
 ipware = FastAPIIpWare(proxy_count=1, default_strict=True)
 

{fastapi_ipware-0.2.0 → fastapi_ipware-1.0.0}/README.md

@@ -27,10 +27,6 @@ uv add fastapi-ipware
 
 ## Quick Start
 
-`trusted` is true only when the request came through the proxies configured with `proxy_count` or `proxy_list`.
-
-`proxy_count=N` returns the address just left of the N rightmost proxies, instead of the first public address, and rejects a shorter chain. `X-Forwarded-For: 203.0.113.10, 10.0.0.1, 10.0.0.2` returns `203.0.113.10` with no `proxy_count`, and `10.0.0.1` with `proxy_count=1`.
-
 ### Using FastAPI Dependency Injection
 
 ```python
@@ -44,6 +40,8 @@ ipware = FastAPIIpWare()
 
 @app.get("/")
 async def get_ip(client: Annotated[ClientIpResult, Depends(ipware)]):
+    # trusted is true only when the request came through the proxies
+    # configured with proxy_count or proxy_list
     ip, trusted = client
     return {
         "ip": str(ip) if ip else None,
@@ -132,6 +130,10 @@ Validate that requests pass through the expected number of proxies:
 
 ```python
 # Expect exactly 1 proxy (e.g., AWS ALB).
+# proxy_count=N returns the address just left of the N rightmost proxies,
+# instead of the first public address, and rejects a shorter chain.
+# X-Forwarded-For: 203.0.113.10, 10.0.0.1, 10.0.0.2 returns 203.0.113.10
+# with no proxy_count, and 10.0.0.1 with proxy_count=1.
 # default_strict applies to Depends(ipware), dependency(), and IpWareMiddleware.
 ipware = FastAPIIpWare(proxy_count=1, default_strict=True)
 

{fastapi_ipware-0.2.0 → fastapi_ipware-1.0.0}/fastapi_ipware/__init__.py

@@ -13,27 +13,84 @@ IpAddressType = ipaddress.IPv4Address | ipaddress.IPv6Address
 ClientIpResult = tuple[IpAddressType | None, bool]
 
 DEFAULT_PRECEDENCE: tuple[str, ...] = (
-    # Provider-specific headers (highest reliability)
-    "CF-Connecting-IP",  # Cloudflare
-    "True-Client-IP",  # Cloudflare Enterprise, Akamai
-    "Fastly-Client-IP",  # Fastly, Firebase
-    "Fly-Client-IP",  # Fly.io
-    "X-Client-IP",  # Microsoft Azure
-    "X-Azure-ClientIP",  # Azure Front Door
-    "DO-Connecting-IP",  # DigitalOcean App Platform
-    "X-Cluster-Client-IP",  # Rackspace Cloud Load Balancers
-    "X-Appengine-User-IP",  # Google App Engine
-    "X-Envoy-External-Address",  # Envoy / Istio
-    # Generic headers (fallback)
-    "X-Forwarded-For",  # Generic, used by AWS ELB, nginx, etc.
-    "X-Real-IP",  # NGINX
-    "Forwarded-For",  # Plain IP list variant
-    "Forwarded",  # RFC 7239 (for=...;proto=...)
-    "Client-IP",  # Akamai, Cloudflare fallback
-    "REMOTE_ADDR",  # Direct connection fallback
+    # provider-specific headers (highest reliability)
+    # cloudflare
+    "CF-Connecting-IP",
+    # cloudflare enterprise, akamai
+    "True-Client-IP",
+    # fastly, firebase
+    "Fastly-Client-IP",
+    # fly.io
+    "Fly-Client-IP",
+    # microsoft azure
+    "X-Client-IP",
+    # azure front door
+    "X-Azure-ClientIP",
+    # digitalocean app platform
+    "DO-Connecting-IP",
+    # rackspace cloud load balancers
+    "X-Cluster-Client-IP",
+    # google app engine
+    "X-Appengine-User-IP",
+    # envoy / istio
+    "X-Envoy-External-Address",
+    # generic headers (fallback)
+    # generic, used by aws elb, nginx, etc
+    "X-Forwarded-For",
+    # nginx
+    "X-Real-IP",
+    # plain ip list variant
+    "Forwarded-For",
+    # rfc 7239 (for=...;proto=...)
+    "Forwarded",
+    # akamai, cloudflare fallback
+    "Client-IP",
+    # direct connection fallback
+    "REMOTE_ADDR",
 )
 
 
+def _expand_header_variants(header: str) -> tuple[str, ...]:
+    "Expand a single header name into its natural and WSGI variants"
+    if header == "REMOTE_ADDR":
+        return ("REMOTE_ADDR",)
+
+    if header.startswith("HTTP_"):
+        return (header, header[5:].replace("_", "-"))
+
+    return (header, f"HTTP_{header.upper().replace('-', '_')}")
+
+
+def _expand_header_precedence(precedence: tuple[str, ...]) -> tuple[str, ...]:
+    "Expand header precedence tuple to include natural and WSGI formats"
+    expanded: list[str] = []
+    for header in precedence:
+        for variant in _expand_header_variants(header):
+            if variant in expanded:
+                continue
+
+            expanded.append(variant)
+
+    return tuple(expanded)
+
+
+def _build_request_meta(request: HTTPConnection) -> dict[str, str]:
+    "Build a metadata dictionary containing WSGI and natural headers from request"
+    # populate both wsgi-style headers and original starlette headers
+    meta = {
+        f"HTTP_{name.upper().replace('-', '_')}": value
+        for name, value in request.headers.items()
+    }
+    for name, value in request.headers.items():
+        meta[name] = value
+
+    if request.client:
+        # map starlette's connection info to remote_addr fallback
+        meta["REMOTE_ADDR"] = request.client.host
+
+    return meta
+
+
 class FastAPIIpWare(IpWare):
     """
     A FastAPI/Starlette-native wrapper around python-ipware that eliminates
@@ -84,31 +141,15 @@ class FastAPIIpWare(IpWare):
         if precedence is None:
             precedence = DEFAULT_PRECEDENCE
 
-        # Store FastAPI-style precedence for reference
+        # store fastapi-style precedence for reference
         self._fastapi_precedence = precedence
         self.default_strict = default_strict
 
-        # Expand precedence to support both natural and WSGI formats
-        expanded_precedence: list[str] = []
-        for header in precedence:
-            if header == "REMOTE_ADDR":
-                if "REMOTE_ADDR" not in expanded_precedence:
-                    expanded_precedence.append("REMOTE_ADDR")
-            elif header.startswith("HTTP_"):
-                if header not in expanded_precedence:
-                    expanded_precedence.append(header)
-                non_http = header[5:].replace("_", "-")
-                if non_http not in expanded_precedence:
-                    expanded_precedence.append(non_http)
-            else:
-                if header not in expanded_precedence:
-                    expanded_precedence.append(header)
-                wsgi_form = f"HTTP_{header.upper().replace('-', '_')}"
-                if wsgi_form not in expanded_precedence:
-                    expanded_precedence.append(wsgi_form)
+        # expand precedence to support both natural and wsgi formats
+        expanded_precedence = _expand_header_precedence(precedence)
 
         super().__init__(
-            tuple(expanded_precedence),
+            expanded_precedence,
             leftmost=leftmost,
             proxy_count=proxy_count,
             proxy_list=proxy_list,
@@ -117,32 +158,32 @@ class FastAPIIpWare(IpWare):
 
     @property
     def precedence(self) -> tuple[str, ...]:
-        """Header precedence tuple from the active engine."""
+        "Header precedence tuple from the active engine"
         return getattr(self.engine, "precedence", ())
 
     @property
     def leftmost(self) -> bool:
-        """Leftmost setting from the active engine."""
+        "Leftmost setting from the active engine"
         return getattr(self.engine, "leftmost", True)
 
     @property
     def proxy_count(self) -> int | None:
-        """Proxy count setting from the active engine."""
+        "Proxy count setting from the active engine"
         return getattr(self.engine, "proxy_count", None)
 
     @property
     def proxy_list(self) -> list[str]:
-        """Proxy list setting from the active engine."""
+        "Proxy list setting from the active engine"
         return getattr(self.engine, "proxy_list", [])
 
     def __call__(self, request: HTTPConnection) -> ClientIpResult:
-        """FastAPI route dependency injection entrypoint."""
+        "FastAPI route dependency injection entrypoint"
         return self.get_client_ip_from_request(request, strict=self.default_strict)
 
     def dependency(
         self, strict: bool | None = None
     ) -> Callable[[HTTPConnection], ClientIpResult]:
-        """Return a FastAPI dependency. An omitted strict flag uses default_strict."""
+        "Return a FastAPI dependency. An omitted strict flag uses default_strict"
 
         def _dep(request: HTTPConnection) -> ClientIpResult:
             return self.get_client_ip_from_request(request, strict=strict)
@@ -150,14 +191,18 @@ class FastAPIIpWare(IpWare):
         return _dep
 
     def get_ip(self, request: HTTPConnection) -> IpAddressType | None:
-        """Return only the client IP address (or None if unresolvable)."""
+        "Return only the client IP address (or None if unresolvable)"
         ip, _ = self.get_client_ip_from_request(request, strict=self.default_strict)
+
         return ip
 
     def get_ip_str(self, request: HTTPConnection) -> str | None:
-        """Return the client IP address as a string (or None if unresolvable)."""
+        "Return the client IP address as a string (or None if unresolvable)"
         ip = self.get_ip(request)
-        return str(ip) if ip is not None else None
+        if ip is None:
+            return None
+
+        return str(ip)
 
     def get_client_ip_from_request(
         self, request: HTTPConnection, strict: bool | None = None
@@ -176,22 +221,10 @@ class FastAPIIpWare(IpWare):
                 - ip_address: IPv4Address or IPv6Address object (or None if not found)
                 - trusted_route: True if request came through trusted proxies, False otherwise
         """
-        if strict is None:
-            strict = self.default_strict
+        effective_strict = self.default_strict if strict is None else strict
+        meta = _build_request_meta(request)
 
-        # Populate both WSGI-style headers and original Starlette headers
-        meta = {
-            f"HTTP_{name.upper().replace('-', '_')}": value
-            for name, value in request.headers.items()
-        }
-        for name, value in request.headers.items():
-            meta[name] = value
-
-        if request.client:
-            # Map Starlette's connection info to REMOTE_ADDR fallback
-            meta["REMOTE_ADDR"] = request.client.host
-
-        return self.get_client_ip(meta, strict=strict)
+        return self.get_client_ip(meta, strict=effective_strict)
 
 
 class IpWareMiddleware:
@@ -216,15 +249,17 @@ class IpWareMiddleware:
         self.strict = strict
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
-        if scope["type"] in ("http", "websocket"):
-            conn = HTTPConnection(scope)
-            ip, trusted = self.ipware.get_client_ip_from_request(
-                conn, strict=self.strict
-            )
-            scope.setdefault("state", {})
-            scope["state"]["client_ip"] = ip
-            scope["state"]["ip_trusted"] = trusted
-            scope["state"]["client_ip_str"] = str(ip) if ip is not None else None
+        if scope["type"] not in ("http", "websocket"):
+            await self.app(scope, receive, send)
+            return
+
+        conn = HTTPConnection(scope)
+        ip, trusted = self.ipware.get_client_ip_from_request(conn, strict=self.strict)
+
+        scope.setdefault("state", {})
+        scope["state"]["client_ip"] = ip
+        scope["state"]["ip_trusted"] = trusted
+        scope["state"]["client_ip_str"] = str(ip) if ip is not None else None
 
         await self.app(scope, receive, send)
 

{fastapi_ipware-0.2.0 → fastapi_ipware-1.0.0}/fastapi_ipware/version.py

@@ -1,26 +1,27 @@
-"""Version handling for fastapi-ipware."""
+"Version handling for fastapi-ipware"
 
 import importlib.metadata
 from pathlib import Path
 
 
 def is_local_source_checkout() -> bool:
-    """Check if the code is running from a local source checkout."""
+    "Check if the code is running from a local source checkout"
     package_dir = Path(__file__).resolve().parent
-    # Since this is a flat layout (module-root = ""), repo root is the parent of the package dir
+
+    # since this is a flat layout (module-root = ""), repo root is the parent of the package dir
     repo_root = package_dir.parent
 
     return (repo_root / ".git").exists() and (repo_root / "pyproject.toml").exists()
 
 
 def get_version() -> str:
-    """Get the version string, appending .dev if running from source."""
+    "Get the version string, appending .dev if running from source"
     try:
-        # Try to get the version of the installed package
+        # try to get the version of the installed package
         version = importlib.metadata.version("fastapi-ipware")
     except importlib.metadata.PackageNotFoundError:
-        # Fallback for local development if not installed
-        version = "0.1.0"
+        # fallback for local development if not installed
+        version = "1.0.0"
 
     if not is_local_source_checkout():
         return version

{fastapi_ipware-0.2.0 → fastapi_ipware-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-ipware"
-version = "0.2.0"
+version = "1.0.0"
 description = "FastAPI/Starlette-native wrapper for python-ipware to get client IP addresses"
 keywords = [
     "fastapi",

{fastapi_ipware-0.2.0 → fastapi_ipware-1.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-ipware"
-version = "0.2.0"
+version = "1.0.0"
 description = "FastAPI/Starlette-native wrapper for python-ipware to get client IP addresses"
 keywords = [
     "fastapi",