flask-Humanify 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

flask_humanify/__init__.py

@@ -4,11 +4,12 @@ Flask-Humanify
 A Flask extension that protects against bots and DDoS attacks.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 from . import utils
 from .humanify import Humanify
 from .features.rate_limiter import RateLimiter
+from .features.error_handler import ErrorHandler
 
 
-__all__ = ["Humanify", "RateLimiter", "utils"]
+__all__ = ["Humanify", "RateLimiter", "ErrorHandler", "utils"]

flask_humanify/features/error_handler.py

@@ -0,0 +1,177 @@
+from typing import Final, Optional
+from flask import Flask, render_template
+
+
+ERROR_CODES: Final[dict] = {
+    400: {
+        "title": "Bad Request",
+        "description": "The server could not understand your request due to invalid syntax.",
+    },
+    401: {
+        "title": "Unauthorized",
+        "description": "You must authenticate yourself to get the requested response.",
+    },
+    403: {
+        "title": "Forbidden",
+        "description": "You do not have access rights to the content.",
+    },
+    404: {
+        "title": "Not Found",
+        "description": "The server cannot find the requested resource.",
+    },
+    405: {
+        "title": "Method Not Allowed",
+        "description": "The request method is known by the server but is not supported by the target resource.",
+    },
+    406: {
+        "title": "Not Acceptable",
+        "description": (
+            "The server cannot produce a response matching the list of acceptable values "
+            "defined in your request's proactive content negotiation headers."
+        ),
+    },
+    408: {
+        "title": "Request Timeout",
+        "description": (
+            "The server did not receive a complete request message from you within the time that "
+            "it was prepared to wait."
+        ),
+    },
+    409: {
+        "title": "Conflict",
+        "description": (
+            "The request could not be completed due to a conflict with the current state of "
+            "the target resource."
+        ),
+    },
+    410: {
+        "title": "Gone",
+        "description": "The requested resource is no longer available and will not be available again.",
+    },
+    411: {
+        "title": "Length Required",
+        "description": "The server refuses to accept the request without a defined Content-Length header.",
+    },
+    412: {
+        "title": "Precondition Failed",
+        "description": (
+            "The server does not meet one of the preconditions that you put on "
+            "the request header fields."
+        ),
+    },
+    413: {
+        "title": "Payload Too Large",
+        "description": "The request entity is larger than limits defined by the server.",
+    },
+    414: {
+        "title": "URI Too Long",
+        "description": "The URI requested by you is longer than the server is willing to interpret.",
+    },
+    415: {
+        "title": "Unsupported Media Type",
+        "description": "The media format of the requested data is not supported by the server.",
+    },
+    416: {
+        "title": "Range Not Satisfiable",
+        "description": "The range specified by the Range header field in your request can't be fulfilled.",
+    },
+    417: {
+        "title": "Expectation Failed",
+        "description": (
+            "The expectation given in your request's Expect header field could not be met by at "
+            "least one of the inbound servers."
+        ),
+    },
+    418: {
+        "title": "I'm a teapot",
+        "description": "The web server rejects the attempt to make coffee with a teapot.",
+    },
+    422: {
+        "title": "Unprocessable Entity",
+        "description": "The request was well-formed but was unable to be followed due to semantic errors.",
+    },
+    423: {
+        "title": "Locked",
+        "description": "The resource that is being accessed is locked.",
+    },
+    424: {
+        "title": "Failed Dependency",
+        "description": "The request failed due to failure of a previous request.",
+    },
+    428: {
+        "title": "Precondition Required",
+        "description": "The origin server requires your request to be conditional.",
+    },
+    429: {
+        "title": "Too Many Requests",
+        "description": "You have sent too many requests in a given amount of time.",
+    },
+    431: {
+        "title": "Request Header Fields Too Large",
+        "description": (
+            "The server is unwilling to process your request because its header "
+            "fields are too large."
+        ),
+    },
+    451: {
+        "title": "Unavailable For Legal Reasons",
+        "description": "The server is denying access to the resource as a consequence of a legal demand.",
+    },
+    500: {
+        "title": "Internal Server Error",
+        "description": "The server has encountered a situation it doesn't know how to handle.",
+    },
+    501: {
+        "title": "Not Implemented",
+        "description": "The request method is not supported by the server and cannot be handled.",
+    },
+    502: {
+        "title": "Bad Gateway",
+        "description": (
+            "The server, while acting as a gateway or proxy, received an invalid response from "
+            "the upstream server."
+        ),
+    },
+    503: {
+        "title": "Service Unavailable",
+        "description": "The server is not ready to handle the request.",
+    },
+    504: {
+        "title": "Gateway Timeout",
+        "description": (
+            "The server is acting as a gateway or proxy and did not receive a timely response "
+            "from the upstream server."
+        ),
+    },
+    505: {
+        "title": "HTTP Version Not Supported",
+        "description": "The HTTP version used in your request is not supported by the server.",
+    },
+}
+
+
+class ErrorHandler:
+    def __init__(self, app: Flask, errors: Optional[list[int]] = None):
+        self.app = app
+
+        for error_code in errors or ERROR_CODES:
+            self.app.register_error_handler(error_code, self.handle_error)
+
+    def handle_error(self, error: Exception) -> tuple:
+        """Render exception page with appropriate error information."""
+        code = getattr(error, "code", type(error).__name__)
+        info = ERROR_CODES.get(code, {})
+        title = f"{code} | {info.get('title', 'Error')}"
+        message = (
+            info.get("description")
+            or str(error).split(" ", 1)[-1].strip()
+            or "An error occurred"
+        )
+
+        return render_template("exception.html").replace(
+            "EXCEPTION_TITLE", title
+        ).replace("EXCEPTION_CODE", str(code)).replace(
+            "EXCEPTION_MESSAGE", message
+        ), getattr(
+            error, "code", 500
+        )

flask_humanify/templates/audio_challenge.html

@@ -198,7 +198,9 @@
                 href="{{ url_for('humanify.challenge', return_url=return_url) }}"
             >
                 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
-                    <path d="M96 416q-14 0-23-9t-9-23V128q0-14 9-23t23-9h320q14 0 23 9t9 23v256q0 14-9 23t-23 9zm88-176q20 0 34-14t14-34-14-34-34-14-34 14-14 34 14 34 34 14m216 128v-64l-64-64-96 96-56-57-88 89z"/>
+                    <path
+                        d="M96 416q-14 0-23-9t-9-23V128q0-14 9-23t23-9h320q14 0 23 9t9 23v256q0 14-9 23t-23 9zm88-176q20 0 34-14t14-34-14-34-34-14-34 14-14 34 14 34 34 14m216 128v-64l-64-64-96 96-56-57-88 89z"
+                    />
                 </svg>
                 Image challenge
             </a>

flask_humanify/templates/exception.html

@@ -0,0 +1,66 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>EXCEPTION_TITLE</title>
+        <style>
+            body {
+                font-family: system-ui, sans-serif;
+                background: #f2f2f2;
+                color: #181818;
+                margin: 0;
+                line-height: 1.5;
+                text-align: center;
+                display: grid;
+                place-items: center;
+                height: 100vh;
+                padding: 0 20px;
+            }
+
+            @media (prefers-color-scheme: dark) {
+                body {
+                    background: #121212;
+                    color: #f2f2f2;
+                }
+
+                .btn {
+                    background: #f2f2f2;
+                    color: #121212;
+                }
+            }
+
+            .content {
+                max-width: 600px;
+            }
+
+            h1 {
+                font-size: 64px;
+                margin: 15px 0;
+            }
+
+            p {
+                font-size: 20px;
+                margin: 15px 0;
+                opacity: 0.8;
+            }
+
+            .btn {
+                display: inline-block;
+                padding: 12px 24px;
+                background: #181818;
+                color: #f2f2f2;
+                border-radius: 6px;
+                text-decoration: none;
+                margin-top: 20px;
+            }
+        </style>
+    </head>
+    <body>
+        <div class="content">
+            <h1>EXCEPTION_CODE</h1>
+            <p>EXCEPTION_MESSAGE</p>
+            <a href="/" class="btn">Back to home</a>
+        </div>
+    </body>
+</html>

{flask_humanify-0.2.1.dist-info → flask_humanify-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flask-Humanify
-Version: 0.2.1
+Version: 0.2.2
 Summary: Protect against bots and DDoS attacks
 Author-email: TN3W <tn3w@protonmail.com>
 License-Expression: Apache-2.0
@@ -129,3 +129,80 @@ Add the extension to your Flask app:
 app = Flask(__name__)
 humanify = Humanify(app)
 ```
+
+## Additional Features
+
+### Rate Limiting
+
+Flask-Humanify includes a rate limiting feature to protect your application from excessive requests:
+
+```python
+from flask import Flask
+from flask_humanify import Humanify, RateLimiter
+
+app = Flask(__name__)
+humanify = Humanify(app)
+# Default: 10 requests per 10 seconds
+rate_limiter = RateLimiter(app)
+
+# Or customize rate limits
+rate_limiter = RateLimiter(app, max_requests=20, time_window=30)
+```
+
+The rate limiter will automatically:
+
+- Track requests by IP address
+- Hash IPs for privacy
+- Redirect to a rate-limited page when limits are exceeded
+- Ignore rate limits for special pages like the rate-limited and access-denied pages
+
+### Error Handling
+
+Flask-Humanify provides a clean error handling system:
+
+```python
+from flask import Flask
+from flask_humanify import Humanify, ErrorHandler
+
+app = Flask(__name__)
+humanify = Humanify(app)
+# Handle all standard HTTP errors
+error_handler = ErrorHandler(app)
+
+# Or handle only specific error codes
+error_handler = ErrorHandler(app, errors=[404, 429, 500])
+```
+
+The error handler:
+
+- Renders user-friendly error pages
+- Uses the custom exception.html template
+- Provides appropriate error messages and descriptions
+- Includes HTTP status codes and titles
+
+### Complete Example
+
+Here's a complete example combining all features:
+
+```python
+from flask import Flask
+from flask_humanify import Humanify, RateLimiter, ErrorHandler
+
+app = Flask(__name__)
+# Setup core protection
+humanify = Humanify(app, challenge_type="one_click", image_dataset="animals")
+humanify.register_middleware(action="challenge")
+
+# Add rate limiting
+rate_limiter = RateLimiter(app, max_requests=15, time_window=60)
+
+# Add error handling
+error_handler = ErrorHandler(app)
+
+@app.route("/")
+def index():
+    return "Hello, Human!"
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```

{flask_humanify-0.2.1.dist-info → flask_humanify-0.2.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-flask_humanify/__init__.py,sha256=Edab8NW0fWYhaFb8NVIJapnUp3bYY9BxBnPP6xB41-Q,269
+flask_humanify/__init__.py,sha256=rvTDStRFUl6sFNVgm7NKEA3fkH2gP7osDl3IuUy-SNU,334
 flask_humanify/humanify.py,sha256=C-HhqWfvENMyOjU2LJ8aUW0npLm2LavuiTcvAf_LTCM,22179
 flask_humanify/memory_server.py,sha256=NlGYrHuH6S7Ei7I5gc78aYvZvEq6bUz-lgLhuiCXTEM,30339
 flask_humanify/utils.py,sha256=mG8oZL6U52yDWOlE3umqf5NNuwKB-LnhMjr_xdpQcAo,18581
@@ -7,14 +7,16 @@ flask_humanify/datasets/animals.pkl,sha256=zhOY-J3h18ZMBE5D9q_ujQc7ZW1WRNcuYfM4J
 flask_humanify/datasets/characters.pkl,sha256=tEbGnbi5S9Y2Us9arVghdV43luqOAiGTQMLiU2bka6U,12756114
 flask_humanify/datasets/ipset.json,sha256=YNPqwI109lYkfvZeOPsoDH_dKJxOCs0G2nvx_s2mvqU,30601191
 flask_humanify/datasets/keys.pkl,sha256=sYzgJ5SP5SluWwyatFnWc-hj8rzwaOEOMVLJOw4VZik,32763786
+flask_humanify/features/error_handler.py,sha256=bLOyaS6jtkLyxf7RviXD5fVrJ7fBAd9I8Zt2Q1m54n8,6123
 flask_humanify/features/rate_limiter.py,sha256=QMIwfEllTDup6jxckEbE83PlJZeLw-0SvyxPqzXJYzU,2204
 flask_humanify/templates/access_denied.html,sha256=p8ea_9gvv83aYFHaVKKedmQr6M8Z7NyHJK_OT3jdTOs,3169
-flask_humanify/templates/audio_challenge.html,sha256=1QR-EQs3CJleT64jWxAreJG-RIUHuQox-jXswOCemXg,6397
+flask_humanify/templates/audio_challenge.html,sha256=Tvs7mTah59n4I-w5N8ABcW8AMPN8zAAcFYZUXBm6NH0,6442
+flask_humanify/templates/exception.html,sha256=OcAuyoBQ5wLMQvFAVi2LS7gcDsLmCpkuHCBQoh_eGTg,1711
 flask_humanify/templates/grid_challenge.html,sha256=cToubxQvI7bJ-BKS9wceIvsAmp6h2EGYLhgyRr6pFxU,7179
 flask_humanify/templates/one_click_challenge.html,sha256=21WOkYWrW48GXpVPBMPrEJ7Iq5JawkrXKUyUUfxWmTc,5996
 flask_humanify/templates/rate_limited.html,sha256=Bv98MoetuSJGpWkDaQfhl7JwcWJiGaG2gwqxvSphaTM,3114
-flask_humanify-0.2.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-flask_humanify-0.2.1.dist-info/METADATA,sha256=ENhuFvYdzqH3muoRNtpf000eF8b6PBcaNkTo8HLyI5M,4239
-flask_humanify-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-flask_humanify-0.2.1.dist-info/top_level.txt,sha256=9-c6uhxwCpPE3BJYge1Y9Z_bYmWitI0fY5RgqMiFWr0,15
-flask_humanify-0.2.1.dist-info/RECORD,,
+flask_humanify-0.2.2.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+flask_humanify-0.2.2.dist-info/METADATA,sha256=5Mrphy_GSkMiJVc7ZEdkiO2_-eVILQ1plCWlxI7bO0E,6092
+flask_humanify-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+flask_humanify-0.2.2.dist-info/top_level.txt,sha256=9-c6uhxwCpPE3BJYge1Y9Z_bYmWitI0fY5RgqMiFWr0,15
+flask_humanify-0.2.2.dist-info/RECORD,,