Merge pull request psf#71 from isudox/feature/optimization

Add typing hints, and remove unnecessary code for constructor.

requests_html.py

@@ -25,6 +25,7 @@
 # Typing.
 _Find = Union[List['Element'], 'Element']
 _XPath = Union[List[str], List['Element'], str, 'Element']
+_Result = Union[List['Result'], 'Result']
 _HTML = Union[str, bytes]
 _BaseHTML = str
 _UserAgent = str
@@ -45,6 +46,7 @@
 except AssertionError:
     raise RuntimeError('Requests-HTML requires Python 3.6+!')
 
+
 class BaseParser:
     """A basic HTML/Element Parser, for Humans.
 
@@ -103,7 +105,8 @@ def encoding(self) -> _Encoding:
         return self._encoding if self._encoding else self.default_encoding
 
     @encoding.setter
-    def encoding(self, enc):
+    def encoding(self, enc: str) -> None:
+        """Property setter for self.encoding."""
         self._encoding = enc
 
     @property
@@ -135,7 +138,8 @@ def full_text(self) -> _Text:
         return self.lxml.text_content()
 
     def find(self, selector: str, first: bool = False, _encoding: str = None) -> _Find:
-        """Given a CSS Selector, returns a list of :class:`Element <Element>` objects.
+        """Given a CSS Selector, returns a list of
+        :class:`Element <Element>` objects or a single one.
 
         :param selector: CSS Selector to use.
         :param first: Whether or not to return just the first result.
@@ -148,9 +152,13 @@ def find(self, selector: str, first: bool = False, _encoding: str = None) -> _Fi
         - ``a#someID``
         - ``a[target=_blank]``
 
-        See W3School's `CSS Selectors Reference <https://www.w3schools.com/cssref/css_selectors.asp>`_ for more details.
+        See W3School's `CSS Selectors Reference
+        <https://www.w3schools.com/cssref/css_selectors.asp>`_
+        for more details.
 
-        If ``first`` is ``True``, only returns the first :class:`Element <Element>` found."""
+        If ``first`` is ``True``, only returns the first
+        :class:`Element <Element>` found.
+        """
 
         encoding = _encoding or self.encoding
         elements = [
@@ -162,7 +170,7 @@ def find(self, selector: str, first: bool = False, _encoding: str = None) -> _Fi
 
     def xpath(self, selector: str, first: bool = False, _encoding: str = None) -> _XPath:
         """Given an XPath selector, returns a list of
-        :class:`Element <Element>` objects.
+        :class:`Element <Element>` objects or a single one.
 
         :param selector: XPath Selector to use.
         :param first: Whether or not to return just the first result.
@@ -189,15 +197,15 @@ def xpath(self, selector: str, first: bool = False, _encoding: str = None) -> _X
         return _get_first_or_list(elements, first)
 
     def search(self, template: str) -> Result:
-        """Searches the :class:`Element <Element>` for the given Parse template.
+        """Search the :class:`Element <Element>` for the given Parse template.
 
         :param template: The Parse template to use.
         """
 
         return parse_search(template, self.html)
 
-    def search_all(self, template: str) -> Result:
-        """Searches the :class:`Element <Element>` (multiple times) for the given parse
+    def search_all(self, template: str) -> _Result:
+        """Search the :class:`Element <Element>` (multiple times) for the given parse
         template.
 
         :param template: The Parse template to use.
@@ -270,7 +278,7 @@ class Element(BaseParser):
     :param default_encoding: Which encoding to default to.
     """
 
-    def __init__(self, *, element, url, default_encoding) -> None:
+    def __init__(self, *, element, url: _URL, default_encoding: _DefaultEncoding = None) -> None:
         super(Element, self).__init__(element=element, url=url, default_encoding=default_encoding)
         self.element = element
 
@@ -300,7 +308,7 @@ class HTML(BaseParser):
     :param default_encoding: Which encoding to default to.
     """
 
-    def __init__(self, *, url: str = DEFAULT_URL, html: _HTML, default_encoding: str =DEFAULT_ENCODING) -> None:
+    def __init__(self, *, url: str = DEFAULT_URL, html: _HTML, default_encoding: str = DEFAULT_ENCODING) -> None:
 
         # Convert incoming unicode HTML into bytes.
         if isinstance(html, str):
@@ -444,7 +452,7 @@ def user_agent(style=None) -> _UserAgent:
     return useragent[style] if style else DEFAULT_USER_AGENT
 
 
-def _get_first_or_list(l, first=True):
+def _get_first_or_list(l, first=False):
     if first:
         try:
             return l[0]
@@ -459,8 +467,8 @@ class HTMLSession(requests.Session):
     amongst other things.
     """
 
-    def __init__(self, mock_browser=True, *args, **kwargs):
-        super(HTMLSession, self).__init__(*args, **kwargs)
+    def __init__(self, mock_browser=True):
+        super(HTMLSession, self).__init__()
 
         # Mock a web browser's user agent.
         if mock_browser: