flaresolverr-cli 0.2.0__tar.gz

flaresolverr_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Xavier-Lam
+
+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.

flaresolverr_cli-0.2.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: flaresolverr-cli
+Version: 0.2.0
+Summary: A requests.Session that proxies through a FlareSolverr instance.
+Home-page: https://github.com/Xavier-Lam/FlareSolverrSession
+Author: Xavier-Lam
+Author-email: xavierlam7@hotmail.com
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mock; python_version < "3" and extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# FlareSolverr Session
+
+[![PyPI version](https://badge.fury.io/py/flaresolverr-session.svg)](https://pypi.org/project/flaresolverr-session/)
+[![CI](https://github.com/Xavier-Lam/FlareSolverrSession/actions/workflows/ci.yml/badge.svg)](https://github.com/Xavier-Lam/FlareSolverrSession/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Xavier-Lam/FlareSolverrSession/branch/master/graph/badge.svg)](https://codecov.io/gh/Xavier-Lam/FlareSolverrSession)
+
+A [`requests.Session`](https://docs.python-requests.org/) that transparently routes all HTTP requests through a [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) instance, allowing you to bypass Cloudflare protection with a familiar Python API.
+
+The project ships with a RPC client for direct access to the FlareSolverr JSON API, and a command-line interface (CLI) for quick requests and session management.
+
+This project is not responsible for solving challenges itself, it only forwards requests to *FlareSolverr*. If *FlareSolverr* fails to solve a challenge, it will raise an exception. Any issues related to challenge solving should be reported to the *FlareSolverr* project.
+
+
+## Installation
+
+```bash
+pip install flaresolverr-session
+```
+
+or
+
+```bash
+pip install flaresolverr-cli
+``` 
+
+## Prerequisites
+
+You need a running [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) instance. The quickest way is via Docker:
+
+```bash
+docker run -d --name=flaresolverr -p 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from flaresolverr_session import Session
+
+with Session("http://localhost:8191/v1") as session:
+    response = session.get("https://example.com")
+    print(response.status_code)
+    print(response.text)
+```
+
+It is recommended to set a persistent `session_id`.
+
+```python
+session = Session(
+    "http://localhost:8191/v1",
+    session_id="my-persistent-session",
+)
+```
+
+#### Response Object
+A `FlareSolverr` object is attached to the `response` as `response.flaresolverr`. It contains metadata about the request and challenge solving process returned by *FlareSolverr*.
+
+| Attribute | Description |
+|---|---|
+| `flaresolverr.status` | `"ok"` on success |
+| `flaresolverr.message` | Message from FlareSolverr (e.g. challenge status) |
+| `flaresolverr.user_agent` | User-Agent used by FlareSolverr's browser |
+| `flaresolverr.start` / `flaresolverr.end` | Request timestamps (ms) |
+| `flaresolverr.version` | FlareSolverr server version |
+
+#### Exception Handling
+
+| Exception | Description |
+|---|---|
+| `FlareSolverrError` | Base exception. Inherits from `requests.exceptions.RequestException`. |
+| `FlareSolverrChallengeError` | Challenge could not be solved. |  
+| `FlareSolverrCaptchaError` | CAPTCHA detected. Inherits from `FlareSolverrChallengeError`. |
+| `FlareSolverrTimeoutError` | Request timed out. |
+| `FlareSolverrSessionError` | Session creation/destruction failed. |
+| `FlareSolverrUnsupportedMethodError` | Unsupported HTTP method or content type. |
+
+### Command-Line Interface
+
+After installation, you can use the `flaresolverr-cli` command. It is a convenient CLI tool to send HTTP requests through FlareSolverr and manage sessions.
+
+It will output json response from FlareSolverr. If the FlareSolverr URL is not provided via `-f`, it will use the `FLARESOLVERR_URL` environment variable (defaulting to `http://localhost:8191/v1`).
+
+#### Sending requests
+
+The `request` command is the default — you can omit the word `request`:
+
+```bash
+flaresolverr-cli https://example.com -o output.html
+
+# GET with a custom FlareSolverr URL
+flaresolverr-cli -f http://localhost:8191/v1 https://example.com
+
+# POST with form data (data implies POST)
+flaresolverr-cli https://example.com -d "key=value&foo=bar"
+```
+
+#### Managing sessions
+
+```bash
+# Create a session (auto-generated name)
+flaresolverr-cli -f http://localhost:8191/v1 session create my-session
+
+# List all active sessions
+flaresolverr-cli session list
+
+# Destroy a session
+flaresolverr-cli session destroy my-session
+```
+
+### RPC Tool
+
+The `flaresolverr_rpc` module provides a programmatic interface to the FlareSolverr JSON API, useful when you need low-level access to the raw API responses.
+
+```python
+from flaresolverr_rpc import RPC
+
+with RPC("http://localhost:8191/v1") as rpc:
+    # Session management
+    rpc.session.create(session_id="my-session", proxy="http://proxy:8080")
+    sessions = rpc.session.list()
+    print(sessions["sessions"])
+
+    # HTTP requests
+    result = rpc.request.get("https://example.com", session_id="my-session")
+    print(result["solution"]["url"])
+    print(result["solution"]["response"])  # HTML body
+
+    result = rpc.request.post(
+        "https://example.com",
+        data="key=value",
+        session_id="my-session",
+    )
+
+    # Cleanup
+    rpc.session.destroy("my-session")
+```
+
+All methods return the raw JSON response dict from FlareSolverr.
+
+
+## Limitations
+
+- **Only GET and  `application/x-www-form-urlencoded` POST** are supported. Otherwise, it will raise `FlareSolverrUnsupportedMethodError`. 
+- **Headers returned by FlareSolverr** may be empty for some sites, depending on the FlareSolverr version and configuration. Empty HTTP status will be regarded as `200`. See [FlareSolverr#1162](https://github.com/FlareSolverr/FlareSolverr/issues/1162).

flaresolverr_cli-0.2.0/README.md

@@ -0,0 +1,145 @@
+# FlareSolverr Session
+
+[![PyPI version](https://badge.fury.io/py/flaresolverr-session.svg)](https://pypi.org/project/flaresolverr-session/)
+[![CI](https://github.com/Xavier-Lam/FlareSolverrSession/actions/workflows/ci.yml/badge.svg)](https://github.com/Xavier-Lam/FlareSolverrSession/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Xavier-Lam/FlareSolverrSession/branch/master/graph/badge.svg)](https://codecov.io/gh/Xavier-Lam/FlareSolverrSession)
+
+A [`requests.Session`](https://docs.python-requests.org/) that transparently routes all HTTP requests through a [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) instance, allowing you to bypass Cloudflare protection with a familiar Python API.
+
+The project ships with a RPC client for direct access to the FlareSolverr JSON API, and a command-line interface (CLI) for quick requests and session management.
+
+This project is not responsible for solving challenges itself, it only forwards requests to *FlareSolverr*. If *FlareSolverr* fails to solve a challenge, it will raise an exception. Any issues related to challenge solving should be reported to the *FlareSolverr* project.
+
+
+## Installation
+
+```bash
+pip install flaresolverr-session
+```
+
+or
+
+```bash
+pip install flaresolverr-cli
+``` 
+
+## Prerequisites
+
+You need a running [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) instance. The quickest way is via Docker:
+
+```bash
+docker run -d --name=flaresolverr -p 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from flaresolverr_session import Session
+
+with Session("http://localhost:8191/v1") as session:
+    response = session.get("https://example.com")
+    print(response.status_code)
+    print(response.text)
+```
+
+It is recommended to set a persistent `session_id`.
+
+```python
+session = Session(
+    "http://localhost:8191/v1",
+    session_id="my-persistent-session",
+)
+```
+
+#### Response Object
+A `FlareSolverr` object is attached to the `response` as `response.flaresolverr`. It contains metadata about the request and challenge solving process returned by *FlareSolverr*.
+
+| Attribute | Description |
+|---|---|
+| `flaresolverr.status` | `"ok"` on success |
+| `flaresolverr.message` | Message from FlareSolverr (e.g. challenge status) |
+| `flaresolverr.user_agent` | User-Agent used by FlareSolverr's browser |
+| `flaresolverr.start` / `flaresolverr.end` | Request timestamps (ms) |
+| `flaresolverr.version` | FlareSolverr server version |
+
+#### Exception Handling
+
+| Exception | Description |
+|---|---|
+| `FlareSolverrError` | Base exception. Inherits from `requests.exceptions.RequestException`. |
+| `FlareSolverrChallengeError` | Challenge could not be solved. |  
+| `FlareSolverrCaptchaError` | CAPTCHA detected. Inherits from `FlareSolverrChallengeError`. |
+| `FlareSolverrTimeoutError` | Request timed out. |
+| `FlareSolverrSessionError` | Session creation/destruction failed. |
+| `FlareSolverrUnsupportedMethodError` | Unsupported HTTP method or content type. |
+
+### Command-Line Interface
+
+After installation, you can use the `flaresolverr-cli` command. It is a convenient CLI tool to send HTTP requests through FlareSolverr and manage sessions.
+
+It will output json response from FlareSolverr. If the FlareSolverr URL is not provided via `-f`, it will use the `FLARESOLVERR_URL` environment variable (defaulting to `http://localhost:8191/v1`).
+
+#### Sending requests
+
+The `request` command is the default — you can omit the word `request`:
+
+```bash
+flaresolverr-cli https://example.com -o output.html
+
+# GET with a custom FlareSolverr URL
+flaresolverr-cli -f http://localhost:8191/v1 https://example.com
+
+# POST with form data (data implies POST)
+flaresolverr-cli https://example.com -d "key=value&foo=bar"
+```
+
+#### Managing sessions
+
+```bash
+# Create a session (auto-generated name)
+flaresolverr-cli -f http://localhost:8191/v1 session create my-session
+
+# List all active sessions
+flaresolverr-cli session list
+
+# Destroy a session
+flaresolverr-cli session destroy my-session
+```
+
+### RPC Tool
+
+The `flaresolverr_rpc` module provides a programmatic interface to the FlareSolverr JSON API, useful when you need low-level access to the raw API responses.
+
+```python
+from flaresolverr_rpc import RPC
+
+with RPC("http://localhost:8191/v1") as rpc:
+    # Session management
+    rpc.session.create(session_id="my-session", proxy="http://proxy:8080")
+    sessions = rpc.session.list()
+    print(sessions["sessions"])
+
+    # HTTP requests
+    result = rpc.request.get("https://example.com", session_id="my-session")
+    print(result["solution"]["url"])
+    print(result["solution"]["response"])  # HTML body
+
+    result = rpc.request.post(
+        "https://example.com",
+        data="key=value",
+        session_id="my-session",
+    )
+
+    # Cleanup
+    rpc.session.destroy("my-session")
+```
+
+All methods return the raw JSON response dict from FlareSolverr.
+
+
+## Limitations
+
+- **Only GET and  `application/x-www-form-urlencoded` POST** are supported. Otherwise, it will raise `FlareSolverrUnsupportedMethodError`. 
+- **Headers returned by FlareSolverr** may be empty for some sites, depending on the FlareSolverr version and configuration. Empty HTTP status will be regarded as `200`. See [FlareSolverr#1162](https://github.com/FlareSolverr/FlareSolverr/issues/1162).

flaresolverr_cli-0.2.0/cli.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from __future__ import print_function
+
+import argparse
+import json
+import os
+import sys
+
+from flaresolverr_rpc import RPC
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+
+    main_parser = _build_main_parser()
+
+    # Handle top-level -h/--help when no command specified
+    if not argv or argv == ["-h"] or argv == ["--help"]:
+        main_parser.print_help()
+        return 0
+
+    first_args, remaining = main_parser.parse_known_args(argv)
+    command = first_args.command
+
+    if command == "session":
+        parser = _build_session_parser()
+        args = parser.parse_args([command] + remaining)
+        rpc = RPC(first_args.flaresolverr_url)
+        res = _handle_session(rpc, args)
+        _format_output(res)
+        return 0
+
+    if command == "request":
+        request_argv = remaining
+    elif command is not None:
+        request_argv = [command] + remaining
+    else:
+        main_parser.print_help()
+        return 0
+
+    req_parser = _build_request_parser()
+    args = req_parser.parse_args(request_argv)
+    rpc = RPC(first_args.flaresolverr_url)
+    res = _handle_request(rpc, args)
+    _truncate_response_body(res)
+    _format_output(res)
+    return 0
+
+
+def _build_main_parser():
+    parser = argparse.ArgumentParser(
+        prog="flaresolverr-cli",
+        description="Interact with a FlareSolverr instance",
+        add_help=False,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "commands:\n"
+            "  session             Manage FlareSolverr sessions\n"
+            "  request (default)   Send an HTTP request through FlareSolverr\n\n"
+            "Run 'flaresolverr-cli session --help' or "
+            "'flaresolverr-cli request --help' for more information."
+        ),
+    )
+    parser.add_argument(
+        "-f",
+        "--flaresolverr",
+        dest="flaresolverr_url",
+        default=os.environ.get("FLARESOLVERR_URL", "http://localhost:8191/v1"),
+        help=(
+            "FlareSolverr API endpoint (default: FLARESOLVERR_URL "
+            "env var or http://localhost:8191/v1)"
+        ),
+    )
+    parser.add_argument("command", nargs="?", default=None)
+    return parser
+
+
+def _build_session_parser():
+    parser = argparse.ArgumentParser(
+        prog="flaresolverr-cli",
+        description="Interact with a FlareSolverr instance",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+    session_parser = subparsers.add_parser(
+        "session",
+        help="Manage FlareSolverr sessions",
+    )
+    session_sub = session_parser.add_subparsers(dest="session_action")
+    session_sub.required = True
+
+    # session create
+    create_parser = session_sub.add_parser("create", help="Create a session")
+    create_parser.add_argument(
+        "name",
+        nargs="?",
+        default=None,
+        help="Optional session name",
+    )
+    create_parser.add_argument(
+        "--proxy",
+        default=None,
+        help="Proxy URL (e.g. http://proxy:8080)",
+    )
+
+    # session list
+    session_sub.add_parser("list", help="List active sessions")
+
+    # session destroy
+    destroy_parser = session_sub.add_parser("destroy", help="Destroy a session")
+    destroy_parser.add_argument(
+        "session_id",
+        help="Session identifier to destroy",
+    )
+
+    return parser
+
+
+def _build_request_parser():
+    parser = argparse.ArgumentParser(
+        prog="flaresolverr-cli request",
+        description="Send an HTTP request through FlareSolverr",
+    )
+    parser.add_argument(
+        "url",
+        help="URL to request",
+    )
+    parser.add_argument(
+        "-m",
+        "--method",
+        default=None,
+        choices=["GET", "POST"],
+        help="HTTP method (default: GET, or POST when -d is given)",
+    )
+    parser.add_argument(
+        "-s",
+        "--session-id",
+        dest="session_id",
+        default=None,
+        help="FlareSolverr session id to use",
+    )
+    parser.add_argument(
+        "-d",
+        "--data",
+        default=None,
+        help="POST data (x-www-form-urlencoded)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        dest="output_file",
+        default=None,
+        help="Write response body to file",
+    )
+    parser.add_argument(
+        "-t",
+        "--timeout",
+        type=int,
+        default=None,
+        help="Request timeout in milliseconds (default: 60000)",
+    )
+    parser.add_argument(
+        "--proxy",
+        default=None,
+        help="Proxy URL (e.g. http://proxy:8080)",
+    )
+    parser.add_argument(
+        "--session-ttl-minutes",
+        dest="session_ttl_minutes",
+        type=int,
+        default=None,
+        help="Auto-rotate sessions older than this many minutes",
+    )
+    parser.add_argument(
+        "--return-only-cookies",
+        dest="return_only_cookies",
+        action="store_true",
+        default=False,
+        help="Return only cookies, omitting the response body",
+    )
+    parser.add_argument(
+        "--return-screenshot",
+        dest="return_screenshot",
+        action="store_true",
+        default=False,
+        help="Include a Base64 PNG screenshot in the response",
+    )
+    parser.add_argument(
+        "--wait",
+        dest="wait_in_seconds",
+        type=int,
+        default=None,
+        help="Extra seconds to wait after the challenge is solved",
+    )
+    parser.add_argument(
+        "--disable-media",
+        dest="disable_media",
+        action="store_true",
+        default=False,
+        help="Disable loading images, CSS and fonts",
+    )
+    return parser
+
+
+def _handle_session(rpc, args):
+    action = args.session_action
+
+    if action == "create":
+        return rpc.session.create(
+            session_id=getattr(args, "name", None),
+            proxy=getattr(args, "proxy", None),
+        )
+    elif action == "list":
+        return rpc.session.list()
+    elif action == "destroy":
+        return rpc.session.destroy(args.session_id)
+    else:
+        raise ValueError("Unknown session action: %s" % action)
+
+
+def _handle_request(rpc, args):
+    """Send a request through FlareSolverr and display the result.
+
+    Parameters:
+        rpc (RPC): RPC client instance.
+        args (argparse.Namespace): Parsed CLI arguments.
+    """
+    method = getattr(args, "method", None)
+    data = getattr(args, "data", None)
+    if method is None:
+        method = "POST" if data else "GET"
+
+    kwargs = {}
+    session_id = getattr(args, "session_id", None)
+    if session_id:
+        kwargs["session_id"] = session_id
+    timeout = getattr(args, "timeout", None)
+    if timeout:
+        kwargs["max_timeout"] = timeout
+    proxy = getattr(args, "proxy", None)
+    if proxy:
+        kwargs["proxy"] = proxy
+    session_ttl_minutes = getattr(args, "session_ttl_minutes", None)
+    if session_ttl_minutes is not None:
+        kwargs["session_ttl_minutes"] = session_ttl_minutes
+    if getattr(args, "return_only_cookies", False):
+        kwargs["return_only_cookies"] = True
+    if getattr(args, "return_screenshot", False):
+        kwargs["return_screenshot"] = True
+    wait_in_seconds = getattr(args, "wait_in_seconds", None)
+    if wait_in_seconds is not None:
+        kwargs["wait_in_seconds"] = wait_in_seconds
+    if getattr(args, "disable_media", False):
+        kwargs["disable_media"] = True
+
+    if method == "POST":
+        result = rpc.request.post(args.url, data=data, **kwargs)
+    else:
+        result = rpc.request.get(args.url, **kwargs)
+
+    # Write body to file if requested
+    output_file = getattr(args, "output_file", None)
+    if output_file:
+        body = result.get("solution", {}).get("response", "")
+        if isinstance(body, bytes):
+            content = body
+        else:
+            content = body.encode("utf-8")
+        with open(output_file, "wb") as f:
+            f.write(content)
+
+    return result
+
+
+def _truncate_response_body(data, max_length=200):
+    solution = data.get("solution")
+    if not solution:
+        return data
+    body = solution.get("response", "")
+    if body and len(body) > max_length:
+        solution["response"] = body[:max_length] + "...[%d letters]" % len(body)
+    return data
+
+
+def _format_output(data):
+    print(json.dumps(data, indent=2))
+
+
+if __name__ == "__main__":
+    sys.exit(main())