From 383b4f74261388d149138804f4d0d41791f22691 Mon Sep 17 00:00:00 2001 From: Kevin Lloyd Bernal Date: Wed, 26 Oct 2022 23:16:49 +0800 Subject: [PATCH] update 'Item Class' to 'item class' --- docs/advanced/fields.rst | 22 ++++++++++---------- docs/intro/overrides.rst | 32 +++++++++++++++--------------- tests/po_lib_to_return/__init__.py | 8 ++++---- web_poet/pages.py | 2 +- web_poet/rules.py | 14 ++++++------- 5 files changed, 39 insertions(+), 39 deletions(-) diff --git a/docs/advanced/fields.rst b/docs/advanced/fields.rst index 85073d04..64e39619 100644 --- a/docs/advanced/fields.rst +++ b/docs/advanced/fields.rst @@ -185,7 +185,7 @@ Item Classes ------------ In all previous examples, ``to_item`` methods are returning ``dict`` -instances. It is common to use Item Classes (e.g. dataclasses or +instances. It is common to use item classes (e.g. dataclasses or attrs instances) instead of unstructured dicts to hold the data: .. code-block:: python @@ -209,7 +209,7 @@ attrs instances) instead of unstructured dicts to hold the data: ) :mod:`web_poet.fields` supports it, by allowing to parametrize -:class:`~.ItemPage` with an Item Class: +:class:`~.ItemPage` with an item class: .. code-block:: python @@ -217,13 +217,13 @@ attrs instances) instead of unstructured dicts to hold the data: class ProductPage(ItemPage[Product]): # ... -When :class:`~.ItemPage` is parametrized with an Item Class, +When :class:`~.ItemPage` is parametrized with an item class, its ``to_item()`` method starts to return item instances, instead of ``dict`` instances. In the example above ``ProductPage.to_item`` method returns ``Product`` instances. -Defining an Item Class may be an overkill if you only have a single Page Object, -but Item Classes are of a great help when +Defining an item class may be an overkill if you only have a single Page Object, +but item classes are of a great help when * you need to extract data in the same format from multiple websites, or * if you want to define the schema upfront. @@ -231,7 +231,7 @@ but Item Classes are of a great help when Error prevention ~~~~~~~~~~~~~~~~ -Item Classes play particularly well with the +Item classes play particularly well with the :func:`@field ` decorator, preventing some of the errors, which may happen if results are plain "dicts". @@ -256,7 +256,7 @@ Consider the following badly written page object: def nane(self): return self.response.css(".name").get() -Because the ``Product`` Item Class is used, a typo ("nane" instead of "name") +Because the ``Product`` item class is used, a typo ("nane" instead of "name") is detected at runtime: the creation of a ``Product`` instance would fail with a ``TypeError``, because of the unexpected keyword argument "nane". @@ -265,7 +265,7 @@ detected: the ``price`` argument is required, but there is no extraction method this attribute, so ``Product.__init__`` will raise another ``TypeError``, indicating that a required argument is missing. -Without an Item Class, none of these errors are detected. +Without an item class, none of these errors are detected. Changing Item Class ~~~~~~~~~~~~~~~~~~~ @@ -335,7 +335,7 @@ to the item: # ... Note how :class:`~.Returns` is used as one of the base classes of -``CustomFooPage``; it allows to change the Item Class returned by a page object. +``CustomFooPage``; it allows to change the item class returned by a page object. Removing fields (as well as renaming) is a bit more tricky. @@ -370,13 +370,13 @@ is passed, and ``name`` is the only field ``CustomItem`` supports. To recap: -* Use ``Returns[NewItemType]`` to change the Item Class in a subclass. +* Use ``Returns[NewItemType]`` to change the item class in a subclass. * Don't use ``skip_nonitem_fields=True`` when your Page Object corresponds to an item exactly, or when you're only adding fields. This is a safe approach, which allows to detect typos in field names, even for optional fields. * Use ``skip_nonitem_fields=True`` when it's possible for the Page Object - to contain more ``@fields`` than defined in the Item Class, e.g. because + to contain more ``@fields`` than defined in the item class, e.g. because Page Object is inherited from some other base Page Object. Caching diff --git a/docs/intro/overrides.rst b/docs/intro/overrides.rst index 25c825c5..1831bfa4 100644 --- a/docs/intro/overrides.rst +++ b/docs/intro/overrides.rst @@ -13,7 +13,7 @@ could declare that for a given set of URL patterns, a specific Page Object must be used instead of another Page Object. The :class:`~.ApplyRule` also supports pointing to the item returned by a specific -Page Object if it both matches the URL pattern and the Item Class specified in the +Page Object if it both matches the URL pattern and the item class specified in the rule. This enables **web-poet** to be used effectively by other frameworks like @@ -56,7 +56,7 @@ Creating Overrides ------------------ To simplify the code examples in the next few subsections, let's assume that -these Item Classes have been predefined: +these item classes have been predefined: .. code-block:: python @@ -105,8 +105,8 @@ Let's take a look at how the following code is structured: The code above declares that: - - The Page Objects return ``Product`` and ``SimilarProduct`` Item Classes. - Returning Item Classes is a preferred approach as explained in the + - The Page Objects return ``Product`` and ``SimilarProduct`` item classes. + Returning item classes is a preferred approach as explained in the :ref:`web-poet-fields` section. - For sites that match the ``some.example`` pattern, ``ExampleProductPage`` would be used instead of ``GenericProductPage``. @@ -138,7 +138,7 @@ Item Class ~~~~~~~~~~ An alternative approach for the Page Object Overrides example above is to specify -the returned Item Class. For example, we could change the previous example into +the returned item class. For example, we could change the previous example into the following: @@ -169,24 +169,24 @@ the following: Let's break this example down: - The URL patterns are exactly the same as with the previous code example. - - The ``@handle_urls`` decorator determines the Item Class to return (i.e. + - The ``@handle_urls`` decorator determines the item class to return (i.e. ``Product``) from the decorated Page Object. - The ``instead_of`` parameter can be omitted in lieu of the derived Item Class from the Page Object which becomes the ``to_return`` attribute in :class:`~.ApplyRule` instances. This means that: - - If a ``Product`` Item Class is requested for URLs matching with the - "some.example" pattern, then the ``Product`` Item Class would come from + - If a ``Product`` item class is requested for URLs matching with the + "some.example" pattern, then the ``Product`` item class would come from the ``to_item()`` method of ``ExampleProductPage``. - Similarly, if a page with a URL matches with "another.example" without - the "/digital-goods/" path, then the ``Product`` Item Class comes from + the "/digital-goods/" path, then the ``Product`` item class comes from the ``AnotherExampleProductPage`` Page Object. - - However, if a ``Product`` Item Class is requested matching with the URL + - However, if a ``Product`` item class is requested matching with the URL pattern of "dual.example/shop/?product=*", a ``SimilarProduct`` - Item Class is returned by the ``DualExampleProductPage``'s ``to_item()`` + item class is returned by the ``DualExampleProductPage``'s ``to_item()`` method instead. -Specifying the Item Class that a Page Object returns makes it possible for +Specifying the item class that a Page Object returns makes it possible for web-poet frameworks to make Page Object usage transparent to end users. For example, a web-poet framework could implement a function like: @@ -196,12 +196,12 @@ For example, a web-poet framework could implement a function like: item = get_item(url, item_class=Product) Here there is no reference to the Page Object being used underneath, you only -need to indicate the desired Item Class, and the web-poet framework +need to indicate the desired item class, and the web-poet framework automatically determines the Page Object to use based on the specified URL and -the specified Item Class. +the specified item class. Note, however, that web-poet frameworks are encouraged to also allow getting a -Page Object instead of an Item Class instance, for scenarios where end users +Page Object instead of an item class instance, for scenarios where end users wish access to Page Object attributes and methods. @@ -211,7 +211,7 @@ Combination ~~~~~~~~~~~ Of course, you can use the combination of both which enables you to specify in -either contexts of Page Objects and Item Classes. +either contexts of Page Objects and item classes. .. code-block:: python diff --git a/tests/po_lib_to_return/__init__.py b/tests/po_lib_to_return/__init__.py index e87a0f18..935e974e 100644 --- a/tests/po_lib_to_return/__init__.py +++ b/tests/po_lib_to_return/__init__.py @@ -97,7 +97,7 @@ def name(self) -> str: @handle_urls("example.com", instead_of=ProductPage) class SimilarProductPage(ProductPage, Returns[ProductSimilar]): """A custom PO inheriting from a base PO returning the same fields but in - a different Item Class. + a different item class. """ expected_instead_of = ProductPage @@ -109,7 +109,7 @@ class SimilarProductPage(ProductPage, Returns[ProductSimilar]): @handle_urls("example.com", instead_of=ProductPage) class MoreProductPage(ProductPage, Returns[ProductMoreFields]): """A custom PO inheriting from a base PO returning more items using a - different Item Class. + different item class. """ expected_instead_of = ProductPage @@ -127,7 +127,7 @@ class LessProductPage( ProductPage, Returns[ProductFewerFields], skip_nonitem_fields=True ): """A custom PO inheriting from a base PO returning less items using a - different Item Class. + different item class. """ expected_instead_of = ProductPage @@ -143,7 +143,7 @@ def brand(self) -> str: @handle_urls("example.com", instead_of=ProductPage, to_return=ProductSimilar) class CustomProductPage(ProductPage, Returns[Product]): """A custom PO inheriting from a base PO returning the same fields but in - a different Item Class. + a different item class. This PO is the same with ``SimilarProductPage`` but passes a ``to_return`` in the ``@handle_urls`` decorator. diff --git a/web_poet/pages.py b/web_poet/pages.py index f54e86ba..77b39af3 100644 --- a/web_poet/pages.py +++ b/web_poet/pages.py @@ -41,7 +41,7 @@ def is_injectable(cls: typing.Any) -> bool: class Returns(typing.Generic[ItemT]): - """Inherit from this generic mixin to change the Item Class used by + """Inherit from this generic mixin to change the item class used by :class:`~.ItemPage`""" @property diff --git a/web_poet/rules.py b/web_poet/rules.py index e47b4366..47564e96 100644 --- a/web_poet/rules.py +++ b/web_poet/rules.py @@ -40,8 +40,8 @@ class ApplyRule: pattern represented by the ``for_patterns`` attribute is matched. * ``instead_of`` - *(optional)* The Page Object that will be **replaced** with the Page Object specified via the ``use`` parameter. - * ``to_return`` - *(optional)* The Item Class that marks the Page Object - to be **used** which is capable of returning that Item Class. + * ``to_return`` - *(optional)* The item class that marks the Page Object + to be **used** which is capable of returning that item class. * ``meta`` - *(optional)* Any other information you may want to store. This doesn't do anything for now but may be useful for future API updates. @@ -74,7 +74,7 @@ class ApplyRule: the Page Object declared in ``use`` should be used instead of ``ReplacedPageObject``. - The ``to_return`` parameter should capture the Item Class that the Page Object + The ``to_return`` parameter should capture the item class that the Page Object is capable of returning. Before passing it to :class:`~.ApplyRule`, the ``to_return`` value is primarily derived from the return class specified from Page Objects that are subclasses of :class:`~.ItemPage` (see this @@ -85,14 +85,14 @@ class ApplyRule: The ``to_return`` parameter is used as a shortcut to directly retrieve the item from the Page Object to be used for a given URL. It works as: - 1. Given a URL and and Item Class that we want, match it respectively + 1. Given a URL and and item class that we want, match it respectively against ``for_patterns`` and ``to_return`` from the registry rules. 2. This could give us a collection of rules. We need to select one based on the highest priority set by `url-matcher`_. 3. When a single rule has been selected, create an instance of the Page Object specified in its ``use`` parameter. 4. Finally, call the ``.to_item()`` method of the Page Object to retrieve - an instance of the Item Class. + an instance of the item class. Using the ``to_return`` parameter basically adds the convenient step #4 above. @@ -200,7 +200,7 @@ def handle_urls( of the `url-matcher `_ package for more information about them. - This decorator is able to derive the Item Class returned by the Page + This decorator is able to derive the item class returned by the Page Object (see :ref:`item-class-example` section for some examples). This is important since it marks what type of item the Page Object is capable of returning for the given URL patterns. For certain advanced cases, you can @@ -216,7 +216,7 @@ def handle_urls( :param include: The URLs that should be handled by the decorated Page Object. :param instead_of: The Page Object that should be `replaced`. - :param to_return: The Item Class holding the data returned by the Page Object. + :param to_return: The item class holding the data returned by the Page Object. This could be omitted as it could be derived from the ``Returns[ItemClass]`` or ``ItemPage[ItemClass]`` declaration of the Page Object. See :ref:`item-classes` section. Code example in :ref:`combination` subsection.