flaresolverr-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{flaresolverr_cli-0.2.0/flaresolverr_cli.egg-info → flaresolverr_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flaresolverr-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: A requests.Session that proxies through a FlareSolverr instance.
 Home-page: https://github.com/Xavier-Lam/FlareSolverrSession
 Author: Xavier-Lam
@@ -109,14 +109,19 @@ A `FlareSolverr` object is attached to the `response` as `response.flaresolverr`
 | `flaresolverr.version` | FlareSolverr server version |
 
 #### Exception Handling
+All exceptions defined in the module based on `FlareSolverrError`, which inherits from `requests.RequestException`. The inheritance hierarchy is as follows:
+
+    requests.RequestException
+    └── FlareSolverrError
+        ├── FlareSolverrResponseError
+        │   ├── FlareSolverrChallengeError
+        └── FlareSolverrUnsupportedMethodError
+
 
 | 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. |
+| `FlareSolverrResponseError` | FlareSolverr returned an error response. The response dict is available as `response_data` attribute. |
+| `FlareSolverrChallengeError` | Challenge solving failed. |
 | `FlareSolverrUnsupportedMethodError` | Unsupported HTTP method or content type. |
 
 ### Command-Line Interface
@@ -142,14 +147,20 @@ flaresolverr-cli https://example.com -d "key=value&foo=bar"
 #### Managing sessions
 
 ```bash
-# Create a session (auto-generated name)
+# Create a session
 flaresolverr-cli -f http://localhost:8191/v1 session create my-session
 
+# Create multiple sessions at once
+flaresolverr-cli session create session1 session2 session3
+
 # List all active sessions
 flaresolverr-cli session list
 
 # Destroy a session
 flaresolverr-cli session destroy my-session
+
+# Clear all sessions
+flaresolverr-cli session clear
 ```
 
 ### RPC Tool
@@ -157,7 +168,7 @@ flaresolverr-cli session destroy my-session
 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
+from flaresolverr_session import RPC
 
 with RPC("http://localhost:8191/v1") as rpc:
     # Session management

{flaresolverr_cli-0.2.0 → flaresolverr_cli-0.2.2}/README.md

@@ -65,14 +65,19 @@ A `FlareSolverr` object is attached to the `response` as `response.flaresolverr`
 | `flaresolverr.version` | FlareSolverr server version |
 
 #### Exception Handling
+All exceptions defined in the module based on `FlareSolverrError`, which inherits from `requests.RequestException`. The inheritance hierarchy is as follows:
+
+    requests.RequestException
+    └── FlareSolverrError
+        ├── FlareSolverrResponseError
+        │   ├── FlareSolverrChallengeError
+        └── FlareSolverrUnsupportedMethodError
+
 
 | 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. |
+| `FlareSolverrResponseError` | FlareSolverr returned an error response. The response dict is available as `response_data` attribute. |
+| `FlareSolverrChallengeError` | Challenge solving failed. |
 | `FlareSolverrUnsupportedMethodError` | Unsupported HTTP method or content type. |
 
 ### Command-Line Interface
@@ -98,14 +103,20 @@ flaresolverr-cli https://example.com -d "key=value&foo=bar"
 #### Managing sessions
 
 ```bash
-# Create a session (auto-generated name)
+# Create a session
 flaresolverr-cli -f http://localhost:8191/v1 session create my-session
 
+# Create multiple sessions at once
+flaresolverr-cli session create session1 session2 session3
+
 # List all active sessions
 flaresolverr-cli session list
 
 # Destroy a session
 flaresolverr-cli session destroy my-session
+
+# Clear all sessions
+flaresolverr-cli session clear
 ```
 
 ### RPC Tool
@@ -113,7 +124,7 @@ flaresolverr-cli session destroy my-session
 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
+from flaresolverr_session import RPC
 
 with RPC("http://localhost:8191/v1") as rpc:
     # Session management

{flaresolverr_cli-0.2.0 → flaresolverr_cli-0.2.2/flaresolverr_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flaresolverr-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: A requests.Session that proxies through a FlareSolverr instance.
 Home-page: https://github.com/Xavier-Lam/FlareSolverrSession
 Author: Xavier-Lam
@@ -109,14 +109,19 @@ A `FlareSolverr` object is attached to the `response` as `response.flaresolverr`
 | `flaresolverr.version` | FlareSolverr server version |
 
 #### Exception Handling
+All exceptions defined in the module based on `FlareSolverrError`, which inherits from `requests.RequestException`. The inheritance hierarchy is as follows:
+
+    requests.RequestException
+    └── FlareSolverrError
+        ├── FlareSolverrResponseError
+        │   ├── FlareSolverrChallengeError
+        └── FlareSolverrUnsupportedMethodError
+
 
 | 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. |
+| `FlareSolverrResponseError` | FlareSolverr returned an error response. The response dict is available as `response_data` attribute. |
+| `FlareSolverrChallengeError` | Challenge solving failed. |
 | `FlareSolverrUnsupportedMethodError` | Unsupported HTTP method or content type. |
 
 ### Command-Line Interface
@@ -142,14 +147,20 @@ flaresolverr-cli https://example.com -d "key=value&foo=bar"
 #### Managing sessions
 
 ```bash
-# Create a session (auto-generated name)
+# Create a session
 flaresolverr-cli -f http://localhost:8191/v1 session create my-session
 
+# Create multiple sessions at once
+flaresolverr-cli session create session1 session2 session3
+
 # List all active sessions
 flaresolverr-cli session list
 
 # Destroy a session
 flaresolverr-cli session destroy my-session
+
+# Clear all sessions
+flaresolverr-cli session clear
 ```
 
 ### RPC Tool
@@ -157,7 +168,7 @@ flaresolverr-cli session destroy my-session
 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
+from flaresolverr_session import RPC
 
 with RPC("http://localhost:8191/v1") as rpc:
     # Session management

{flaresolverr_cli-0.2.0 → flaresolverr_cli-0.2.2}/flaresolverr_cli.egg-info/SOURCES.txt

@@ -1,8 +1,5 @@
 LICENSE
 README.md
-cli.py
-flaresolverr_rpc.py
-flaresolverr_session.py
 setup.py
 flaresolverr_cli.egg-info/PKG-INFO
 flaresolverr_cli.egg-info/SOURCES.txt
@@ -10,6 +7,11 @@ flaresolverr_cli.egg-info/dependency_links.txt
 flaresolverr_cli.egg-info/entry_points.txt
 flaresolverr_cli.egg-info/requires.txt
 flaresolverr_cli.egg-info/top_level.txt
+flaresolverr_session/__init__.py
+flaresolverr_session/cli.py
+flaresolverr_session/exceptions.py
+flaresolverr_session/rpc.py
+flaresolverr_session/session.py
 tests/test_cli.py
 tests/test_rpc.py
 tests/test_session.py

flaresolverr_cli-0.2.2/flaresolverr_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flaresolverr-cli = flaresolverr_session.cli:main

{flaresolverr_cli-0.2.0 → flaresolverr_cli-0.2.2}/flaresolverr_cli.egg-info/top_level.txt

@@ -1,3 +1 @@
-cli
-flaresolverr_rpc
 flaresolverr_session

flaresolverr_cli-0.2.2/flaresolverr_session/__init__.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+from flaresolverr_session.exceptions import (
+    FlareSolverrError,
+    FlareSolverrResponseError,
+    FlareSolverrChallengeError,
+    FlareSolverrUnsupportedMethodError,
+)
+from flaresolverr_session.rpc import RPC
+from flaresolverr_session.session import Session, Response
+
+__title__ = "flaresolverr-session"
+__description__ = "A requests.Session that proxies through a FlareSolverr instance."
+__url__ = "https://github.com/Xavier-Lam/FlareSolverrSession"
+__version__ = "0.2.2"
+__author__ = "Xavier-Lam"
+__author_email__ = "xavierlam7@hotmail.com"
+
+__all__ = [
+    "Session",
+    "Response",
+    "RPC",
+    "FlareSolverrError",
+    "FlareSolverrResponseError",
+    "FlareSolverrChallengeError",
+    "FlareSolverrUnsupportedMethodError",
+    "__version__",
+]

{flaresolverr_cli-0.2.0 → flaresolverr_cli-0.2.2/flaresolverr_session}/cli.py

@@ -4,11 +4,13 @@
 from __future__ import print_function
 
 import argparse
+import base64
 import json
 import os
 import sys
 
-from flaresolverr_rpc import RPC
+from flaresolverr_session.rpc import RPC
+from flaresolverr_session.exceptions import FlareSolverrResponseError
 
 
 def main(argv=None):
@@ -25,29 +27,33 @@ def main(argv=None):
     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
+    try:
+        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
 
-    if command == "request":
-        request_argv = remaining
-    elif command is not None:
-        request_argv = [command] + remaining
-    else:
-        main_parser.print_help()
+        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
-
-    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
+    except FlareSolverrResponseError as exc:
+        format_output(exc.response_data, file=sys.stderr)
+        return 1
 
 
 def _build_main_parser():
@@ -95,9 +101,8 @@ def _build_session_parser():
     create_parser = session_sub.add_parser("create", help="Create a session")
     create_parser.add_argument(
         "name",
-        nargs="?",
-        default=None,
-        help="Optional session name",
+        nargs="+",
+        help="One or more session names to create",
     )
     create_parser.add_argument(
         "--proxy",
@@ -115,6 +120,9 @@ def _build_session_parser():
         help="Session identifier to destroy",
     )
 
+    # session clear
+    session_sub.add_parser("clear", help="Destroy all sessions")
+
     return parser
 
 
@@ -181,11 +189,10 @@ def _build_request_parser():
         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",
+        "--screenshot",
+        dest="screenshot",
+        default=None,
+        help="Write PNG screenshot of the final rendered page after all challenges and waits are completed to given path",
     )
     parser.add_argument(
         "--wait",
@@ -208,14 +215,16 @@ 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),
-        )
+        names = getattr(args, "name", None)
+        proxy = getattr(args, "proxy", None)
+        return [rpc.session.create(session_id=n, proxy=proxy) for n in names]
     elif action == "list":
         return rpc.session.list()
     elif action == "destroy":
         return rpc.session.destroy(args.session_id)
+    elif action == "clear":
+        payload = rpc.session.list()
+        return [rpc.session.destroy(s) for s in payload["sessions"]]
     else:
         raise ValueError("Unknown session action: %s" % action)
 
@@ -247,7 +256,8 @@ def _handle_request(rpc, args):
         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):
+    screenshot_path = getattr(args, "screenshot", None)
+    if screenshot_path:
         kwargs["return_screenshot"] = True
     wait_in_seconds = getattr(args, "wait_in_seconds", None)
     if wait_in_seconds is not None:
@@ -271,21 +281,30 @@ def _handle_request(rpc, args):
         with open(output_file, "wb") as f:
             f.write(content)
 
+    # Write screenshot to file if requested
+    if screenshot_path:
+        screenshot_b64 = result["solution"]["screenshot"]
+        data = base64.b64decode(screenshot_b64)
+        with open(screenshot_path, "wb") as f:
+            f.write(data)
+
     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 = data["solution"]
+    body = solution["response"]
+    if len(body) > max_length:
         solution["response"] = body[:max_length] + "...[%d letters]" % len(body)
+    if solution.get("screenshot"):
+        solution["screenshot"] = "[%d bytes of PNG data]" % len(solution["screenshot"])
     return data
 
 
-def _format_output(data):
-    print(json.dumps(data, indent=2))
+def format_output(data, file=None):
+    if file is None:
+        file = sys.stdout
+    print(json.dumps(data, indent=2), file=file)
 
 
 if __name__ == "__main__":

flaresolverr_cli-0.2.2/flaresolverr_session/exceptions.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+
+import requests
+
+__all__ = [
+    "FlareSolverrError",
+    "FlareSolverrResponseError",
+    "FlareSolverrChallengeError",
+    "FlareSolverrUnsupportedMethodError",
+]
+
+
+class FlareSolverrError(requests.RequestException):
+    """Base exception for FlareSolverr errors."""
+
+
+class FlareSolverrResponseError(FlareSolverrError):
+    """Raised when FlareSolverr returns a non-ok response.
+
+    Attributes:
+        message (str): The error message from FlareSolverr.
+        response_data (dict or None): The original FlareSolverr response dict.
+    """
+
+    def __init__(self, message, response_data=None, **kwargs):
+        super(FlareSolverrResponseError, self).__init__(message, **kwargs)
+        self.message = message or ""
+        self.response_data = response_data
+
+
+class FlareSolverrChallengeError(FlareSolverrResponseError):
+    """Raised when a challenge could not be solved."""
+
+
+class FlareSolverrUnsupportedMethodError(FlareSolverrError):
+    """Raised when an unsupported HTTP method or content type is used."""

flaresolverr_cli-0.2.0/flaresolverr_rpc.py → flaresolverr_cli-0.2.2/flaresolverr_session/rpc.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 from __future__ import print_function
 
+import json
 import os
 
 try:
@@ -10,10 +11,69 @@ except ImportError:
 
 import requests
 
-from flaresolverr_session import Session
+from flaresolverr_session.exceptions import FlareSolverrError, FlareSolverrResponseError
 
+__all__ = [
+    "RPC",
+    "SessionCommand",
+    "RequestCommand",
+    "FlareSolverrError",
+    "FlareSolverrResponseError",
+]
 
-__all__ = ["RPC", "SessionCommand", "RequestCommand"]
+
+class RPC(object):
+    """RPC client for FlareSolverr.
+
+    Provides two sub-command namespaces:
+
+    - :attr:`session` -- :class:`SessionCommand` for session management.
+    - :attr:`request` -- :class:`RequestCommand` for HTTP requests.
+
+    Parameters:
+        flaresolverr_url (str): The FlareSolverr API endpoint
+            (e.g. ``"http://localhost:8191/v1"``).
+        api_session (requests.Session or None): An optional pre-configured
+            session to use for API calls.
+    """
+
+    def __init__(self, flaresolverr_url=None, api_session=None):
+        if flaresolverr_url is None:
+            flaresolverr_url = os.environ.get(
+                "FLARESOLVERR_URL", "http://localhost:8191/v1"
+            )
+        if api_session is None:
+            api_session = requests.Session()
+
+        self._flaresolverr_url = flaresolverr_url
+        self._api_session = api_session
+        self.session = SessionCommand(self)
+        self.request = RequestCommand(self)
+
+    def send(self, payload):
+        """Send a JSON payload to the FlareSolverr endpoint.
+
+        Parameters:
+            payload (dict): The JSON-serialisable payload to send.
+
+        Returns:
+            dict: The parsed JSON response from FlareSolverr.
+
+        Raises:
+            FlareSolverrResponseError: If the response status is
+                not ``"ok"``.
+        """
+        headers = {"Content-Type": "application/json"}
+        resp = self._api_session.post(
+            self._flaresolverr_url,
+            headers=headers,
+            data=json.dumps(payload),
+        )
+        data = resp.json()
+        status = data.get("status", "")
+        if status != "ok":
+            raise FlareSolverrResponseError(data.get("message"), data, response=resp)
+        return data
 
 
 class SessionCommand(object):
@@ -59,7 +119,7 @@ class SessionCommand(object):
                 payload["proxy"] = proxy
             else:
                 payload["proxy"] = {"url": proxy}
-        return self._rpc._session.send(payload)
+        return self._rpc.send(payload)
 
     def list(self):
         """List all active FlareSolverr browser sessions.
@@ -78,7 +138,7 @@ class SessionCommand(object):
                   timestamp (ms).
         """
         payload = {"cmd": "sessions.list"}
-        return self._rpc._session.send(payload)
+        return self._rpc.send(payload)
 
     def destroy(self, session_id):
         """Destroy an existing FlareSolverr browser session.
@@ -102,7 +162,7 @@ class SessionCommand(object):
             "cmd": "sessions.destroy",
             "session": session_id,
         }
-        return self._rpc._session.send(payload)
+        return self._rpc.send(payload)
 
 
 class RequestCommand(object):
@@ -344,43 +404,4 @@ class RequestCommand(object):
         elif cmd == "request.post":
             # FlareSolverr requires postData for request.post; send empty string
             payload["postData"] = ""
-        return self._rpc._session.send(payload)
-
-
-class RPC(object):
-    """RPC client for FlareSolverr.
-
-    Provides two sub-command namespaces:
-
-    - :attr:`session` -- :class:`SessionCommand` for session management.
-    - :attr:`request` -- :class:`RequestCommand` for HTTP requests.
-
-    The underlying transport reuses
-    :meth:`flaresolverr_session.Session.send`, which is the same
-    low-level method used by the high-level
-    :class:`~flaresolverr_session.Session`.
-
-    Parameters:
-        flaresolverr_url (str): The FlareSolverr API endpoint
-            (e.g. ``"http://localhost:8191/v1"``).
-        api_session (requests.Session or None): An optional pre-configured
-            session to use for API calls.
-    """
-
-    def __init__(self, flaresolverr_url=None, api_session=None):
-        if flaresolverr_url is None:
-            flaresolverr_url = os.environ.get(
-                "FLARESOLVERR_URL", "http://localhost:8191/v1"
-            )
-        if api_session is None:
-            api_session = requests.Session()
-
-        self._session = Session(flaresolverr_url, session=api_session)
-        self.session = SessionCommand(self)
-        self.request = RequestCommand(self)
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, *args):
-        pass
+        return self._rpc.send(payload)