refactor get_overrides() to have a simpler interface with consume_modules()

Author: BurnzZ

docs/intro/overrides.rst

@@ -148,18 +148,18 @@ to see the other functionalities.
     rules = default_registry.get_overrides()
 
     # Or, we could also filter out the rules by the module they were defined in
-    rules = default_registry.get_overrides_from("my_project.page_objects")
+    rules = default_registry.get_overrides(filters="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={})
 
 .. note::
 
     Notice in the code sample above where we could filter out the Override rules
-    per module via :meth:`~.PageObjectRegistry.get_overrides_from`. This
-    could also offer another alternative way to organize your Page Object rules
-    using only the ``default_registry``. There's no need to declare multiple
-    :class:`~.PageObjectRegistry` instances and use multiple annotations.
+    per module via the ``filters`` param. This could also offer another alternative
+    way to organize your Page Object rules using only the ``default_registry``.
+    There's no need to declare multiple :class:`~.PageObjectRegistry` instances
+    and use multiple annotations.
 
 .. warning::
 
@@ -182,8 +182,12 @@ to see the other functionalities.
         consume_modules("external_package_A.po", "another_ext_package.lib")
         rules = default_registry.get_overrides()
 
-    **NOTE**: :func:`~.web_poet.overrides.consume_modules` must be called before
-    :meth:`~.PageObjectRegistry.get_overrides` for the imports to properly load.
+        # Fortunately, `get_overrides()` provides a shortcut for the lines above:
+        rules = default_registry.get_overrides(consume=["external_package_A.po", "another_ext_package.lib"])
+
+    **NOTE**: :func:`~.web_poet.overrides.consume_modules` or the ``consume`` param
+    of :meth:`~.PageObjectRegistry.get_overrides` for the imports to properly load.
+    Most especially if you intend to use Page Objects from externally imported packages.
 
 
 A handy CLI tool is also available at your disposal to quickly see the available
@@ -254,16 +258,16 @@ Then we could easily retrieve all Page Objects per subpackage or module like thi
     from web_poet import default_registry, consume_modules
 
     # We can do it per website.
-    rules_gadget = default_registry.get_overrides_from("my_page_obj_project.cool_gadget_site")
-    rules_furniture = default_registry.get_overrides_from("my_page_obj_project.furniture_site")
+    rules_gadget = default_registry.get_overrides(filters="my_page_obj_project.cool_gadget_site")
+    rules_furniture = default_registry.get_overrides(filters="my_page_obj_project.furniture_site")
 
     # It can also drill down to the country domains on a given site.
-    rules_gadget_us = default_registry.get_overrides_from("my_page_obj_project.cool_gadget_site.us")
-    rules_gadget_fr = default_registry.get_overrides_from("my_page_obj_project.cool_gadget_site.fr")
+    rules_gadget_us = default_registry.get_overrides(filters="my_page_obj_project.cool_gadget_site.us")
+    rules_gadget_fr = default_registry.get_overrides(filters="my_page_obj_project.cool_gadget_site.fr")
 
     # Or even drill down further to the specific module.
-    rules_gadget_us_products = default_registry.get_overrides_from("my_page_obj_project.cool_gadget_site.us.products")
-    rules_gadget_us_listings = default_registry.get_overrides_from("my_page_obj_project.cool_gadget_site.us.product_listings")
+    rules_gadget_us_products = default_registry.get_overrides(filters="my_page_obj_project.cool_gadget_site.us.products")
+    rules_gadget_us_listings = default_registry.get_overrides(filters="my_page_obj_project.cool_gadget_site.us.product_listings")
 
     # Or simply all of the Override rules ever declared.
     rules = default_registry.get_overrides()
@@ -273,11 +277,16 @@ Then we could easily retrieve all Page Objects per subpackage or module like thi
     consume_modules("external_package_A.po", "another_ext_package.lib")
     rules = default_registry.get_overrides()
 
+    # Remember, a shortcut for consuming imports would be:
+    rules = default_registry.get_overrides(consume=["external_package_A.po", "another_ext_package.lib"])
+
+
 .. warning::
 
     Remember to consider calling :func:`~.web_poet.overrides.consume_modules`
-    when using :meth:`~.PageObjectRegistry.get_overrides` in case you have some
-    external package containing Page Objects of interest.
+    or the ``consume`` param of :meth:`~.PageObjectRegistry.get_overrides` for the
+    imports to properly load. Most especially if you intend to use Page Objects
+    from externally imported packages.
 
     This enables the :meth:`~.PageObjectRegistry.handle_urls` that annotates
     the external Page Objects to be properly loadeded.
@@ -301,9 +310,9 @@ hierarchy** like this:
     ├── furniture_shop_products.py
     └── furniture_shop_product_listings.py
 
-As such, calling ``default_registry.get_overrides_from()`` would not work
-on projects with a **flat hierarchy**. Thus, we can organize them using our own
-instances of the :class:`~.PageObjectRegistry` instead:
+As such, calling ``default_registry.get_overrides()`` with a ``from`` parameter
+would not effectively work on projects with a **flat hierarchy**. Thus, we can
+organize them using our own instances of the :class:`~.PageObjectRegistry` instead:
 
 .. code-block:: python
 
@@ -385,10 +394,12 @@ retrieve such rules would be:
 
     from web_poet import default_registry
 
-    product_listing_rules = default_registry.get_overrrides_from(
-        "my_page_obj_project.cool_gadget_site.us.product_listings",
-        "my_page_obj_project.cool_gadget_site.fr.product_listings",
-        "my_page_obj_project.furniture_shop.product_listings"
+    product_listing_rules = default_registry.get_overrrides(
+        filters=[
+            "my_page_obj_project.cool_gadget_site.us.product_listings",
+            "my_page_obj_project.cool_gadget_site.fr.product_listings",
+            "my_page_obj_project.furniture_shop.product_listings",
+        ]
     )
 
 On the other hand, we can also create another :class:`~.PageObjectRegistry` instance
@@ -431,7 +442,7 @@ Retrieving all of the Product Listing Override rules would simply be:
     rules = product_listings_registry.get_overrides()
 
     # We can also filter it down further on a per site basis if needed.
-    rules = product_listings_registry.get_overrides_from("my_page_obj_project.cool_gadget_site")
+    rules = product_listings_registry.get_overrides(filters="my_page_obj_project.cool_gadget_site")
 
 Using Overrides from External Packages
 --------------------------------------
@@ -461,6 +472,9 @@ packages** in your project, you can do it like:
     import gadget_sites_page_objects
     from web_poet import PageObjectRegistry, consume_modules, default_registry
 
+    # We're using `consume_modules()` here instead of the `consume` param of
+    # `PageObjectRegistry.get_overrides()` since we need to access the `data`
+    # attribute of the registry even before calling `PageObjectRegistry.get_overrides()`
     consume_modules("ecommerce_page_objects", "gadget_sites_page_objects")
 
     combined_registry = PageObjectRegistry()

tests/test_overrides.py

@@ -2,14 +2,18 @@
 from url_matcher import Patterns
 
 from tests.po_lib_sub import POLibSub
-from tests.po_lib import POTopLevel1, POTopLevel2, POTopLevelOverriden2, secondary_registry
+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 import consume_modules
 from web_poet.overrides import PageObjectRegistry, default_registry
 
 
@@ -40,19 +44,18 @@ def test_list_page_objects_all():
         assert rule.meta == rule.use.expected_meta, rule.use
 
 
-def test_list_page_objects_all_consume_modules():
+def test_list_page_objects_all_consume():
     """A test similar to the one above but calls ``consume_modules()`` to properly
     load the @handle_urls annotations from other modules/packages.
     """
-    consume_modules("tests_extra")
-    rules = default_registry.get_overrides()
+    rules = default_registry.get_overrides(consume="tests_extra")
     page_objects = {po.use for po in rules}
     assert any(["po_lib_sub_not_imported" in po.__module__ for po in page_objects])
 
 
 def test_list_page_objects_from_pkg():
     """Tests that metadata is extracted properly from the po_lib package"""
-    rules = default_registry.get_overrides_from("tests.po_lib")
+    rules = default_registry.get_overrides(filters="tests.po_lib")
     page_objects = {po.use for po in rules}
 
     # Ensure that the "tests.po_lib", which imports another module named
@@ -68,17 +71,20 @@ def test_list_page_objects_from_pkg():
 
 
 def test_list_page_objects_from_single():
-    rules = default_registry.get_overrides_from("tests.po_lib.a_module")
+    rules = default_registry.get_overrides(filters="tests.po_lib.a_module")
     assert len(rules) == 1
     rule = rules[0]
     assert rule.use == POModule
     assert rule.for_patterns == POModule.expected_patterns
     assert rule.instead_of == POModule.expected_overrides
 
+
 def test_list_page_objects_from_multiple():
-    rules = default_registry.get_overrides_from(
-        "tests.po_lib.a_module",
-        "tests.po_lib.nested_package.a_nested_module"
+    rules = default_registry.get_overrides(
+        filters=[
+            "tests.po_lib.a_module",
+            "tests.po_lib.nested_package.a_nested_module",
+        ]
     )
     assert len(rules) == 2
 
@@ -92,22 +98,22 @@ def test_list_page_objects_from_multiple():
 
 
 def test_list_page_objects_from_empty_module():
-    rules = default_registry.get_overrides_from("tests.po_lib.an_empty_module")
+    rules = default_registry.get_overrides(filters="tests.po_lib.an_empty_module")
     assert len(rules) == 0
 
 
 def test_list_page_objects_from_empty_pkg():
-    rules = default_registry.get_overrides_from("tests.po_lib.an_empty_package")
+    rules = default_registry.get_overrides(filters="tests.po_lib.an_empty_package")
     assert len(rules) == 0
 
 
 def test_list_page_objects_from_unknown_module():
     with pytest.raises(ImportError):
-        default_registry.get_overrides_from("tests.po_lib.unknown_module")
+        default_registry.get_overrides(filters="tests.po_lib.unknown_module")
 
 
 def test_list_page_objects_from_imported_registry():
-    rules = secondary_registry.get_overrides_from("tests.po_lib")
+    rules = secondary_registry.get_overrides(filters="tests.po_lib")
     assert len(rules) == 2
     rule_for = {po.use: po for po in rules}
 
@@ -119,13 +125,15 @@ def test_list_page_objects_from_imported_registry():
     assert pones.for_patterns == Patterns(["example.com"])
     assert pones.instead_of == PONestedModuleOverridenSecondary
 
+
 def test_registry_data_from():
     data = default_registry.data_from("tests.po_lib.nested_package")
 
     assert len(data) == 2
     assert PONestedModule in data
     assert PONestedPkg in data
 
+
 def test_cmd():
     from web_poet.__main__ import main
 

web_poet/__main__.py

@@ -42,7 +42,7 @@ def main(args=None):
             rule.for_patterns.priority,
             rule.meta,
         )
-        for rule in default_registry.get_overrides_from(args.module)
+        for rule in default_registry.get_overrides(filters=args.module)
     ]
     print(tabulate.tabulate(table, headers="firstrow"))