Add a way to add a reference into user-agent.

Indeed, before this patch, it wasn't possible to add a reference
to the user-agent without manually giving a custom one.

From now on, one can use the `user-agent.reference` to add a
reference to the user agent. When set, the reference will then be
set to:

	{user-agent}; +reference

Author: funilrys

PyFunceble/cli/entry_points/pyfunceble/cli.py

@@ -103,6 +103,9 @@ def get_configured_value(
     else:
         result = PyFunceble.facility.ConfigLoader.get_configured_value(entry)
 
+    if isinstance(result, str) and "%" in result:
+        result = result.replace("%", "%%")
+
     if negate:
         result = not result
 
@@ -587,6 +590,18 @@ def get_test_control_group_data() -> List[Tuple[List[str], dict]]:
                 "get the latest (automatically) for you.",
             },
         ),
+        (
+            [
+                "--user-agent-reference",
+            ],
+            {
+                "dest": "user_agent.reference",
+                "type": str,
+                "help": "Sets the reference to append to the user agent.\n\n"
+                "This is useful when you want to add a reference to the "
+                "user agent. %s" % get_configured_value("user_agent.reference"),
+            },
+        ),
         (
             [
                 "-vsc",
@@ -833,15 +848,6 @@ def get_output_control_group_data() -> List[Tuple[List[str], dict]]:
                 "default": "all",
             },
         ),
-        (
-            ["--display-datetime"],
-            {
-                "dest": "cli_testing.display_mode.datetime",
-                "action": "store_true",
-                "help": "Activates or disables the display of the datetime of the\n"
-                "test. %s" % get_configured_value("cli_testing.display_mode.datetime"),
-            },
-        ),
         (
             ["--display-datetime-fmt"],
             {

PyFunceble/data/infrastructure/.PyFunceble_production.yaml

@@ -629,6 +629,17 @@ user_agent:
   # CLI Argument: -ua | --user-agent
   custom: null
 
+  # Set the reference to add to the User-Agent.
+  # This is useful when you want to add a reference (e.g. a link) to the User-Agent.
+  #
+  # The reference will be added at the end of the User-Agent in the following format:
+  # {user_agent}; +{reference}
+  #
+  # When set to `null`, no reference will be added.
+  #
+  # CLI Argument: --user-agent-reference
+  reference: null
+
 proxy:
   # Provides everything related to the proxy usage and configuration.
   #

PyFunceble/dataset/user_agent.py

@@ -196,6 +196,30 @@ def is_supported(self, browser_short_name: str, platform: str) -> bool:
             and bool(self[browser_short_name.lower()][platform.lower()])
         )
 
+    def format_user_agent(
+        self, user_agent: str, *, reference: Optional[str] = None
+    ) -> str:
+        """
+        Given a user agent and a reference, it returns the formatted user agent
+        that we have to use.
+
+        :param user_agent:
+            The user agent to format.
+        :param reference:
+            The reference to append to the user agent.
+
+        :return:
+            The formatted user agent.
+        """
+
+        user_agent = user_agent.strip()
+
+        if reference:
+            if user_agent.endswith(";"):
+                return f"{user_agent} +{reference}"
+            return f"{user_agent}; +{reference}"
+        return user_agent
+
     def get_latest(self) -> str:
         """
         Provides the latest user agent for the given platform.
@@ -205,12 +229,19 @@ def get_latest(self) -> str:
             (if exists).
         """
 
+        reference = None
+
         if PyFunceble.storage.CONFIGURATION:
+            reference = PyFunceble.storage.CONFIGURATION.user_agent.reference
+
             if (
                 PyFunceble.storage.CONFIGURATION.user_agent
                 and PyFunceble.storage.CONFIGURATION.user_agent.custom
             ):
-                return PyFunceble.storage.CONFIGURATION.user_agent.custom
+                return self.format_user_agent(
+                    PyFunceble.storage.CONFIGURATION.user_agent.custom,
+                    reference=reference,
+                )
 
             self.set_preferred(
                 PyFunceble.storage.CONFIGURATION.user_agent.browser,
@@ -220,6 +251,9 @@ def get_latest(self) -> str:
         result = self[self.preferred_browser][self.preferred_platform]
 
         if isinstance(result, (list, tuple)):
-            return secrets.choice(result)
+            return self.format_user_agent(
+                secrets.choice(result),
+                reference=reference,
+            )
 
-        return result
+        return self.format_user_agent(result, reference=reference)

PyFunceble/storage.py

@@ -60,7 +60,7 @@
 from PyFunceble.storage_facility import get_config_directory
 
 PROJECT_NAME: str = "PyFunceble"
-PROJECT_VERSION: str = "4.3.0a11.dev (Blue Duckling: Tulip)"
+PROJECT_VERSION: str = "4.3.0a12.dev (Blue Duckling: Tulip)"
 
 DISTRIBUTED_CONFIGURATION_FILENAME: str = ".PyFunceble_production.yaml"
 

docs/use/configuration/parameters/user-agent.md

@@ -30,6 +30,17 @@ user_agent:
   #
   # CLI Argument: -ua | --user-agent
   custom: null
+
+  # Set the reference to add to the User-Agent.
+  # This is useful when you want to add a reference (e.g. a link) to the User-Agent.
+  #
+  # The reference will be added at the end of the User-Agent in the following format:
+  # {user_agent}; +{reference}
+  #
+  # When set to `null`, no reference will be added.
+  #
+  # CLI Argument: --user-agent-reference
+  reference: null
 ```
 
 ## `browser`

tests/dataset/test_user_agent.py

@@ -507,6 +507,35 @@ def test_get_latest_from_config(self) -> None:
 
         self.assertEqual(expected, actual)
 
+    def test_get_latest_from_config_with_reference(self) -> None:
+        """
+        Tests the method which let us get the latest user agent known based
+        on the settings from the configuration file.
+
+        We also ensure that the reference is correctly appended.
+        """
+
+        given_browser = "firefox"
+        given_platform = "win10"
+        given_reference = "https://example.org"
+
+        self.config_loader.custom_config = {
+            "user_agent": {
+                "platform": given_platform,
+                "browser": given_browser,
+                "reference": given_reference,
+            }
+        }
+        self.config_loader.start()
+
+        expected = (
+            self.our_dataset[given_browser][given_platform] + "; +" + given_reference
+        )
+
+        actual = self.user_agent_dataset.get_latest()
+
+        self.assertEqual(expected, actual)
+
     def test_get_latest_from_config_custom(self) -> None:
         """
         Tests the method which let us get the latest user agent known based
@@ -522,6 +551,28 @@ def test_get_latest_from_config_custom(self) -> None:
 
         self.assertEqual(expected, actual)
 
+    def test_get_latest_from_custom_config_with_reference(self) -> None:
+        """
+        Tests the method which let us get the latest user agent known based
+        on the settings from the configuration file.
+
+        In this test, we check the case that the given reference is set.
+        """
+
+        self.config_loader.custom_config = {
+            "user_agent": {
+                "custom": "Hello, World!",
+                "reference": "https://example.org",
+            }
+        }
+        self.config_loader.start()
+
+        expected = "Hello, World!; +https://example.org"
+
+        actual = self.user_agent_dataset.get_latest()
+
+        self.assertEqual(expected, actual)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/pyf_test_dataset.py

@@ -378,7 +378,9 @@
     },
     "platform": {
         "push": False,
-        "preferred_data_origin": "frequent",
+        "preferred_status_origin": "frequent",
+        "checker_priority": ["none"],
+        "checker_exclude": ["none"],
     },
     "debug": {"active": False, "level": "info"},
     "dns": {
@@ -462,6 +464,11 @@
     },
     "proxy": {"global": {"http": None, "https": None}, "rules": []},
     "share_logs": False,
-    "user_agent": {"browser": "chrome", "custom": None, "platform": "linux"},
+    "user_agent": {
+        "browser": "chrome",
+        "custom": None,
+        "platform": "linux",
+        "reference": None,
+    },
     "verify_ssl_certificate": False,
 }

version.yaml

@@ -1,4 +1,4 @@
-current_version: '4.3.0a11.dev (Blue Duckling: Tulip)'
+current_version: '4.3.0a12.dev (Blue Duckling: Tulip)'
 deprecated:
 - 3.0.21
 - 3.1.20