refactor by removing the need for find_page_object_overrides()

CHANGELOG.rst

@@ -5,8 +5,9 @@ Changelog
 TBR
 ------------------
 
-* ``handle_urls`` decorator and ``find_page_object_overrides`` function added.
-* new CLI tool for displaying all available Page Objects: ``web_poet <path>``
+* added a ``PageObjectRegistry`` class which has the  ``handle_urls`` decorator
+  to write override rules.
+* new CLI tool for displaying all available Page Objects: ``web_poet <module>``
 * removed support for Python 3.6
 * added support for Python 3.10
 

docs/intro/overrides.rst

@@ -96,16 +96,19 @@ Viewing all available Overrides
 
 A convenience function is available discover and retrieve all rules from your
 project. Make sure to check out :ref:`Overrides API section <api-overrides>`
-to see the other functionalities of ``find_page_object_overrides``.
+to see the other functionalities.
 
 .. code-block::
 
-    from web_poet import find_page_object_overrides
+    from web_poet import default_registry
 
-    rules = find_page_object_overrides("my_project.page_objects")
+    # Retrieves all rules that were registered in the registry
+    rules = default_registry.get_overrides() 
 
-    print(len(rules))  # 3
+    # Or, we could also filter out the rules by the module they were defined in
+    rules = default_registry.get_overrides_from_module("my_project.page_objects")
 
+    print(len(rules))  # 3
     print(rules[0])  # OverrideRule(for_patterns=Patterns(include=['example.com'], exclude=[], priority=500), use=<class 'my_project.page_objects.ExampleProductPage'>, instead_of=<class 'my_project.page_objects.GenericProductPage'>, meta={})
 
 

tests/po_lib/__init__.py

@@ -5,6 +5,7 @@
 
 from url_matcher import Patterns
 
+from .. import po_sub_lib  # NOTE: this module contains a PO with @handle_rules
 from web_poet import handle_urls, PageObjectRegistry
 
 
@@ -22,7 +23,7 @@ class POTopLevelOverriden2:
     ...
 
 
-secondary_registry = PageObjectRegistry(name="secondary")
+secondary_registry = PageObjectRegistry()
 
 
 # This first annotation is ignored. A single annotation per registry is allowed

tests/po_sub_lib/__init__.py

@@ -0,0 +1,25 @@
+"""This package is being used by tests/po_lib to validate some behaviors on
+external depedencies.
+"""
+from typing import Dict, Any, Callable
+
+from url_matcher import Patterns
+
+from web_poet import handle_urls
+
+
+class POBase:
+    expected_overrides: Callable
+    expected_patterns: Patterns
+    expected_meta: Dict[str, Any]
+
+
+class POSubLibOverriden:
+    ...
+
+
+@handle_urls("sub_example.com", POSubLibOverriden)
+class POSubLib(POBase):
+    expected_overrides = POSubLibOverriden
+    expected_patterns = Patterns(["sub_example.com"])
+    expected_meta = {}  # type: ignore

tests/test_overrides.py

@@ -1,32 +1,53 @@
 import pytest
 from url_matcher import Patterns
 
-from tests.po_lib import POTopLevel1, POTopLevel2, POTopLevelOverriden2
+from tests.po_sub_lib import POSubLib
+from tests.po_lib import POTopLevel1, POTopLevel2, POTopLevelOverriden2, secondary_registry
 from tests.po_lib.a_module import POModule
 from tests.po_lib.nested_package import PONestedPkg
 from tests.po_lib.nested_package.a_nested_module import (
     PONestedModule,
     PONestedModuleOverridenSecondary,
 )
-from web_poet.overrides import find_page_object_overrides, PageObjectRegistry
+from web_poet.overrides import PageObjectRegistry, default_registry
 
 
 POS = {POTopLevel1, POTopLevel2, POModule, PONestedPkg, PONestedModule}
 
 
+def test_list_page_objects_all():
+    rules = default_registry.get_overrides()
+
+    page_objects = {po.use for po in rules}
+
+    # Ensure that ALL Override Rules are returned as long as the given
+    # registry's @handle_urls annotation was used.
+    assert page_objects == POS.union({POSubLib})
+    for rule in rules:
+        assert rule.instead_of == rule.use.expected_overrides, rule.use
+        assert rule.for_patterns == rule.use.expected_patterns, rule.use
+        assert rule.meta == rule.use.expected_meta, rule.use
+
+
 def test_list_page_objects_from_pkg():
     """Tests that metadata is extracted properly from the po_lib package"""
-    rules = find_page_object_overrides("tests.po_lib")
-    assert {po.use for po in rules} == POS
+    rules = default_registry.get_overrides_from_module("tests.po_lib")
+    page_objects = {po.use for po in rules}
+
+    # Ensure that the "tests.po_lib", which imports another module named
+    # "tests.po_sub_lib" which contains @handle_urls decorators, does not
+    # retrieve the override rules from the external package.
+    assert POSubLib not in page_objects
 
+    assert page_objects == POS
     for rule in rules:
         assert rule.instead_of == rule.use.expected_overrides, rule.use
         assert rule.for_patterns == rule.use.expected_patterns, rule.use
         assert rule.meta == rule.use.expected_meta, rule.use
 
 
 def test_list_page_objects_from_module():
-    rules = find_page_object_overrides("tests.po_lib.a_module")
+    rules = default_registry.get_overrides_from_module("tests.po_lib.a_module")
     assert len(rules) == 1
     rule = rules[0]
     assert rule.use == POModule
@@ -35,22 +56,22 @@ def test_list_page_objects_from_module():
 
 
 def test_list_page_objects_from_empty_module():
-    rules = find_page_object_overrides("tests.po_lib.an_empty_module")
+    rules = default_registry.get_overrides_from_module("tests.po_lib.an_empty_module")
     assert len(rules) == 0
 
 
 def test_list_page_objects_from_empty_pkg():
-    rules = find_page_object_overrides("tests.po_lib.an_empty_package")
+    rules = default_registry.get_overrides_from_module("tests.po_lib.an_empty_package")
     assert len(rules) == 0
 
 
 def test_list_page_objects_from_unknown_module():
     with pytest.raises(ImportError):
-        find_page_object_overrides("tests.po_lib.unknown_module")
+        default_registry.get_overrides_from_module("tests.po_lib.unknown_module")
 
 
 def test_list_page_objects_from_imported_registry():
-    rules = find_page_object_overrides("tests.po_lib", registry_name="secondary")
+    rules = secondary_registry.get_overrides_from_module("tests.po_lib")
     assert len(rules) == 2
     rule_for = {po.use: po for po in rules}
 
@@ -63,16 +84,7 @@ def test_list_page_objects_from_imported_registry():
     assert pones.instead_of == PONestedModuleOverridenSecondary
 
 
-def test_list_page_objects_from_non_existing_registry():
-    assert find_page_object_overrides("tests.po_lib", registry_name="not-exist") == []
-
-
 def test_cmd():
     from web_poet.__main__ import main
 
     assert main(["tests.po_lib"]) is None
-
-
-def test_registry_repr():
-    registry = PageObjectRegistry(name="test")
-    assert "name='test'" in str(registry)

web_poet/__init__.py

@@ -1,3 +1,3 @@
 from .pages import WebPage, ItemPage, ItemWebPage, Injectable
 from .page_inputs import ResponseData
-from .overrides import handle_urls, find_page_object_overrides, PageObjectRegistry
+from .overrides import handle_urls, PageObjectRegistry, default_registry

web_poet/__main__.py

@@ -1,9 +1,11 @@
+"""Returns all Override Rules from the default registry."""
+
 import argparse
 from typing import Callable
 
 import tabulate
 
-from web_poet.overrides import find_page_object_overrides
+from web_poet import default_registry
 
 
 def qualified_name(cls: Callable) -> str:
@@ -20,14 +22,6 @@ def main(args=None):
         type=str,
         help="A package or module to list overrides from",
     )
-    parser.add_argument(
-        "--registry",
-        "-n",
-        metavar="REGISTRY_NAME",
-        type=str,
-        help="Registry name to list overrides from",
-        default="default",
-    )
     args = parser.parse_args(args)
     table = [
         (
@@ -48,7 +42,7 @@ def main(args=None):
             rule.for_patterns.priority,
             rule.meta,
         )
-        for rule in find_page_object_overrides(args.module, registry_name=args.registry)
+        for rule in default_registry.get_overrides_from_module(args.module)
     ]
     print(tabulate.tabulate(table, headers="firstrow"))