diff --git a/CHANGELOG.md b/CHANGELOG.md index 6132295..b8cd2f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +## 1.0.4 + +- Enhance: Readme updates ## 1.0.0 Features: diff --git a/README.md b/README.md index 337a070..5d36669 100644 --- a/README.md +++ b/README.md @@ -26,34 +26,32 @@ Use `python-ipware` **only** as an additional layer to bolster your security, no # How to install - 1. easy_install python-ipware - 2. pip install python-ipware - 3. git clone http:#github.com/un33k/python-ipware - a. cd python-ipware - b. run python setup.py install - 4. wget https:#github.com/un33k/python-ipware/zipball/master - a. unzip the downloaded file - b. cd into python-ipware-* directory - c. run python setup.py install +``` +pip install python-ipware +``` +-- or -- +``` +pip3 install python-ipware +``` # How to use -### Using ipware to Retrieve Client IP in Django or Flask +### Using python-ipware to Retrieve Client IP in Django or Flask -Here's a basic example of how to use `ipware` in a view or middleware where the `request` object is available. This can be applied in Django, Flask, or other similar frameworks. +Here's a basic example of how to use `python-ipware` in a view or middleware where the `request` object is available. This can be applied in Django, Flask, or other similar frameworks. ```python -from ipware import Ipware +from ipware import IpWare -# Instantiate Ipware with default values -ipware = Ipware() +# Instantiate IpWare with default values +ipw = IpWare() # Get the META data from the request object -# For Django use request.META, for Flask use request.environ -meta = request.META +meta = request.META # Django +# meta = request.environ # Flask # Get the client IP and the trusted route flag -ip, trusted_route = ipware.get_client_ip(meta) +ip, trusted_route = ipw.get_client_ip(meta) if ip: # The 'ip' is an object of type IPv4Address() or IPv6Address() with properties like: @@ -124,18 +122,16 @@ You can customize the order by providing your own list during initialization whe ```python # specific meta key -ipware = IpWare(precedence=("X_FORWARDED_FOR")) +ipw = IpWare(precedence=("X_FORWARDED_FOR")) # multiple meta keys -ipware = IpWare(precedence=("X_FORWARDED_FOR", "HTTP_X_FORWARDED_FOR")) - -# usage is just to pass in the http request headers +ipw = IpWare(precedence=("X_FORWARDED_FOR", "HTTP_X_FORWARDED_FOR")) # Django (request.META) -ip, proxy_verified = ipware.get_client_ip(meta=request.META) +ip, proxy_verified = ipw.get_client_ip(meta=request.META) # Flask (request.environ) -ip, proxy_verified = ipware.get_client_ip(meta=request.environ) +ip, proxy_verified = ipw.get_client_ip(meta=request.environ) # ... etc. @@ -151,26 +147,26 @@ You can pass your custom list on every call, when calling the proxy-aware api to ```python # In the above scenario, use your load balancer IP address as a way to filter out unwanted requests. -ipware = IpWare(proxy_list=["198.84.193.157"]) +ipw = IpWare(proxy_list=["198.84.193.157"]) # If you have multiple proxies, simply add them to the list -ipware = IpWare(proxy_list=["198.84.193.157", "198.84.193.158"]) +ipw = IpWare(proxy_list=["198.84.193.157", "198.84.193.158"]) # For proxy servers with fixed sub-domain and dynamic IP, use the following pattern. -ipware = IpWare(proxy_list=["177.139.", "177.140"]) +ipw = IpWare(proxy_list=["177.139.", "177.140"]) # usage: non-strict mode (X-Forwarded-For: , , , ) # The request went through our and , then our server # We choose the ip address to the left our and ignore other ips -ip, trusted_route = self.ipware.get_client_ip(meta=request.META) +ip, trusted_route = ipw.get_client_ip(meta=request.META) # usage: strict mode (X-Forwarded-For: , , ) # The request went through our and , then our server # Total ip address are total trusted proxies + client ip # We don't allow far-end proxies, or fake addresses (exact or None) -ip, trusted_route = self.ipware.get_client_ip(meta=request.META, strict=True) +ip, trusted_route = ipw.get_client_ip(meta=request.META, strict=True) ``` In the following `example`, your public load balancer (LB) can be seen as a `trusted` proxy. @@ -190,23 +186,23 @@ You can customize the proxy count by providing your `proxy_count` during initial ```python # In the above scenario, the total number of proxies can be used as a way to filter out unwanted requests. -import ipware +from ipware import IpWare # enforce proxy count -ipware = IpWare(proxy_count=1) +ipw = IpWare(proxy_count=1) # enforce proxy count and trusted proxies -ipware = IpWare(proxy_count=1, proxy_list=["198.84.193.157"]) +ipw = IpWare(proxy_count=1, proxy_list=["198.84.193.157"]) # usage: non-strict mode (X-Forwarded-For: , , , ) # total number of ip addresses are greater than the total count -ip, trusted_route = self.ipware.get_client_ip(meta=request.META) +ip, trusted_route = ipw.get_client_ip(meta=request.META) # usage: strict mode (X-Forwarded-For: , , ) # total number of ip addresses are exactly equal to client ip + proxy_count -ip, trusted_route = self.ipware.get_client_ip(meta=request.META, strict=True) +ip, trusted_route = ipw.get_client_ip(meta=request.META, strict=True) ``` In the following `example`, your public load balancer (LB) can be seen as the `only` proxy. @@ -223,12 +219,12 @@ In the following `example`, your public load balancer (LB) can be seen as the `o ```python # We make best attempt to return the first public IP address based on header precedence # Then we fall back on private, followed by loopback -import ipware +from ipware import IpWare # no proxy enforce in this example -ipware = IpWare() +ipw = IpWare() -ip, _ = ipware.get_client_ip(meta=request.META) +ip, _ = ipw.get_client_ip(meta=request.META) if ip.is_global: print('Public IP') @@ -249,7 +245,7 @@ else if ip.is_reserved: #### Support for IPv4, IPv6, and IP:Port Patterns -`ipware` is designed to handle various IP address formats efficiently: +`python-ipware` is designed to handle various IP address formats efficiently: - **Ports Stripping:** Automatically removes ports from IP addresses, ensuring only the IP is processed. - **IPv6 Unwrapping:** Extracts and processes IPv4 addresses wrapped in IPv6 containers. diff --git a/ipware/__version__.py b/ipware/__version__.py index 976498a..92192ee 100644 --- a/ipware/__version__.py +++ b/ipware/__version__.py @@ -1 +1 @@ -__version__ = "1.0.3" +__version__ = "1.0.4"