Package: easyhtml
=========================================================================EasyHTML :: A package that provides an easy access to elementsof HTML and XHTML documents through the Document Object Model.=========================================================================Homepage: http://easyhtml.sourceforge.net/Author: Taras Gaidukov================================Installation Instructions:================================Dependencies:Python 3.4+Build and install by running:$ python setup.py build$ sudo python setup.py install============Overview:============The package contains a module easyhtml.parser that provides a classeasyhtml.parser.DOMParser (a subclass of html.parser.HTMLParser).This class has a method get_dom() that returns a DOM of parsed documentwhich is an instance of easyhtml.dom.HTMLDocument class:from easyhtml import parserdom_parser = parser.DOMParser()dom_parser.feed('<html>''   <body>''       <h1 class='title'>Hello world!</h1>''       <div id="content">''           <p>First paragraph</p>''           <p>Second paragraph</p>''           <p>Third paragraph</p>''       </div>''   </body>''</html>')document = dom_parser.get_dom()The HTMLDocument class provides an API for access to all elements, theirattributes and contents. Elements of DOM are instances of one of followingclasses:HTMLDocument        - a whole documentHTMLTag             - a tag elementsTextNode            - a text elements including HTML entitiesHTMLComment         - a comments in HTML codeDoctypeDeclaration  - a doctype declaration of the documentEach HTML element provides two variants of its view: raw HTML code and its"clear" text representation (as in web-browsers). A raw HTML code implementedas raw_html property of the element:document.raw_html # returns an HTML code of the documentAnd a text representation is just a str version of the element:str(document) # returns a text representation of the documentText representations of comments and a doctype declaration are empty sincethese elements should be invisible on the page.To access nested elements inside other ones, there are following methods:get_tags_by_name(name)  - returns all tags with specified nameget_children(query)     - returns all tags that match a query*get_element_by_id(id)   - returns a tag with specified id* query is a string that consists of conditions separated with semicolons.A condition is pair of an attribute name and its value written through theequality sign: "attr1=value1; attr2=value2".First two methods return an instance of easyhtml.dom.HTMLCollection class thatcontains found tags. An HTMLCollection object could be empty if there are notags that satisfy the conditions. The get_element_by_id() method returns a tagwith specified id since it's assumed that the id is unique and there is onlyone tag with such id. If the tag is not found, None is returned.Also, the method get_tags_by_name() is implemented as the magic method__getattr__ that allows to get elements by their name just as an attribute:document.div is eqivalent to document.get_tags_by_name('div')The HTMLCollection class is a list-based collection that contains DOM elementsor other HTMLCollection objects. Like a list the collection provides an accessto its elements by their indices using get_element() method and it could beiterated in the for-loop:collection.get_element(0) # returns the first element of the collection# or None if it does not existfor element in collection:# do something with each elementAlso, the method get_element() is implemented as the magic method __getitem__that provides a simplier syntax through the use of the square bracketsoperator, so collection[0] is equivalent to collection.get_element(0)Methods of the HTMLCollection class are similar to those of HTMLTag andHTMLDocument:get_tags_by_name(name)  - returns all tags with specified nameget_children(query)     - returns all tags that match a queryget_element_by_id(id)   - returns a tag with specified idIMPORTANT: Since the HTMLCollection is not an element of the DOM and does notkeep the hierarchy of contained elements, each element in the collection isconsidered as an independent search result. And when a new search is called,the result would be a new HTMLCollection that contains separate collectionsfor each element of the source HTMLCommection object. For instance, say thedocument contains following code:<div id="div1"><p id="p1"></p></div><div id="div2"><p id="p2"></p><p id="p3"></p></div>then a call document.get_tags_by_name('div') returns a collection with twotags:Collection {<div id="div1"><div id="div2">}Then call collection.get_tags_by_name('p') returns a collection that containstwo collections with <p> tags in each one.Collection {Collection {<p id="p1">}Collection {<p id="p2"><p id="p3">}}Such behavior is similar to that the use of the collection in the for-loop andmaking new search requests to each element separately:collection = document.get_tags_by_name('div')for element in collection:sub_collection = element.get_tags_by_name('p')# do something with found tagsThe same result would be if you call a new search request to the collectiondirectly and use the result in the for-loop:collection = document.get_tags_by_name('div')collection = collection.get_tags_by_name('p')for sub_collection in collection:# do something with found tagsOr even shorter:for sub_collection in document.div.p:# do something with found tagsPlease note that the get_element_by_id() method returns a single tag as wellas HTMLTag and HTMLDocument objects do, since it's assumed that the id isunique and there is only one tag with such id in the document even if thehierarhy of its elements has been destroyed.In addition the HTMLCollection class provides a method that helps to refinethe request:filter_tags_by_attrs(query) - filters found elements by specified queryAlso this method is implemented as the magic method __call__, so it's possibleto filter tags using simplier syntax with brackets:document.div(class=someclass) # returns a collection of div elements with# the class "someclass"Note that the filter_tags_by_attrs() method does not create a new level ofnested collections.===========================Package API reference:===========================class easyhtml.parser.DOMParser()Creates a parser instance. The DOMParser is a subclass ofhtml.parser.HTMLParser class. For more details about HTMLParser usage seethe official documentation of HTMLParser at Python's website.DOMParser Methods:DOMParser.get_dom()Returns an instance of HTMLDocument that is the root object of theDocument Object Model.class easyhtml.dom.DoctypeDeclaration(decl)A doctype declaration of the document. Used as an attribute ofeasyhtml.dom.HTMLDocument objects. Is not visible in the str version ofthe document, but it's present in the HTML code.:decl: the text of the declaration, type strDoctypeDeclaration Methods:DoctypeDeclaration.raw_htmlA property that returns a raw HTML code of the declaration. It consists ofthe text passed into constructor between <! and > symbols. For instance,<!DOCTYPE html>DoctypeDeclaration.__str__()Returns a str version of the declaration. It's implicitly called in thestr context. Always returns an empty string since the doctype declarationis invisible on the page.class easyhtml.dom.HTMLComment(text)A comment in the HTML code. It's not visible in the str version of thedocument, but it's present in the HTML code.:text: a text of the comment, type strHTMLComment Methods:HTMLComment.raw_htmlA property that returns a raw HTML code of the comment. It consists of thetext passed into constructor between <!-- and --> symbols. For instance,<!-- Here is a comment -->HTMLComment.__str__()Returns a str version of the comment. It's implicitly called in the strcontext. Always returns an empty string since comments are invisible onthe page.class easyhtml.dom.TextNode()A text data element in the document. It's a container for any visibletext data on the page. Could contain PlainText, NamedEntity andNumEntity objects.TextNode Methods:TextNode.raw_htmlA property that returns a raw HTML code of all contained objects.TextNode.__str__()Returns a str version of the text data. It's implicitly called in the strcontext. Includes corresponding characters instead of contained HTMLentities.TextNode.append(element)Adds an element to the end of the list.:element: an element to append, type easyhtml.dom.HTMLText (a superclassof PlainText, NamedEntity and NumEntity classes.class easyhtml.dom.PlainText(text)A plain text on the page (without HTML entities). It's used inside of theTextNode element only.:text: a text of the element, type strPlainText Methods:PlainText.raw_htmlA property that returns all characters of the text as it is in the HTMLdocument.PlainText.__str__()Returns a str version of the text. It's implicitly called in the strcontext. Replaces sequences of white space characters with single spaces.class easyhtml.dom.NamedEntity(name)A named HTML entity. It's used inside of the TextNode element only. If theentity with specified name does not exist, the KeyError would be rised.:name: a name of the entity, type strNamedEntity Methods:NamedEntity.raw_htmlA property that returns an HTML code of the entity. It consists of thename passed into constructor between & and ; symbols.NamedEntity.__str__()Returns a str version of the entity. It's implicitly called in the strcontext. For instance, it returns the "<" character for the entity withthe code &lt;class easyhtml.dom.NumEntity(num)A numeric HTML entity specified by decimal or hexadecimal code. It's usedinside of the TextNode element only. If the entity with specified numericcode does not exist, the KeyError would be rised.:num: a numeric code of the entity, type strNamedEntity Methods:NamedEntity.raw_htmlA property that returns an HTML code of the entity. It consists of thename passed into constructor between &# and ; symbols.NamedEntity.__str__()Returns a str version of the entity. It's implicitly called in the strcontext. For instance, it returns the "<" character for the entity withthe code &#60; or &#x3c;class HTMLTag(name, attrs)An HTML tag. Could be single such as <br> or complex such as <p>...</p>.Complex tags could contain other elements (TextNode, HTMLComment orHTMLTag).:name: a name of the tag, type str:attrs: a list of tuples with attributes of the tag,format [(attr1, value1), (attr2: value2)]HTMLTag Methods:HTMLTag.singleAproperty that indicates whether the tag is single, i.e. does not requirean endtag. The result depends on the name of the tag: there is a list ofthe single tags and if the name matches any item from the list, the tag isconsidered as single.HTMLTag.raw_htmlA property that returns an HTML code of the tag. It consists of thestart tag, inner HTML code and the end tag.HTMLTag.__str__()Returns a str version of the tag. It's implicitly called in the strcontext. It consists of the str versions of all contained elements.For instance, it returns "Hello, world!" for the tag<p>Hello, world!</p>HTMLTag.start_tagA property that returns an HTML code of the start tag. It consists of thename and attributes of the tag in the angle brackets:<name attr1="value1" attr2="value2">HTMLTag.end_tagA property that returns an HTML code the end tag. It consists of the namewith the slash on the front in the angle brackets: </name>HTMLTag.inner_htmlA property that returns HTML codes of all contained elements.HTMLTag.get_attributes()Returns a dictionary of attributes.HTMLTag.get_attr(name):Returns a value of the attribute with specified name of None if suchattribute does not exist.:name: a name of the attribute, type strHTMLTag.check_attr(name, value)Returns True if the value of the attribute with specified name matchesthe specified value. Otherwise returns False.Note that the "class" attribute in the HTML could be defined as a list ofseveral CSS classes separated by the white space characters. The methodreturns True if specified value of the "class" attribute matches one ofthose classes in theHTML. For instance, if the tag is defined as<div class="foo bar">, then check_attr("class", "foo") returns True andcheck_attr("class", "bar") returns True as well.:name: a name of the attribute, tupe str:value: a value of the atribute, type strHTMLTag.check_attrs(query)Returns True if all attributes of the tag and its values match specifiedquery. Otherwise returns False. The query is a string of pairs attr=valueseparated by semicolons and any number of spaces. For instance,"attr1=value1; attr2=value2":query: a query string, type strHTMLTag.append(element)Adds an element to the end of the list.:element: an element to append, allowed types:easyhtml.dom.HTMLTextNodeeasyhtml.dom.HTMLTageasyhtml.dom.HTMLCommentHTMLTags.tagsA property that returns a generator object that generates all containedtags of the tag.HTMLTag.get_all_tags()Returns a generator object that generates all contained tags of the tagincluding all their nested tags recursively.HTMLTag.get_tags_by_name(name)Returns an easyhtml.dom.HTMLCollection object contains tags with specifiedname including nested tags. The same functionality is provided by gettingthe tag's name as an attribute: tag.get_tags_by_name("name") = tag.name:name: a name of search tags, type strHTMLTag.get_children(query)Returns an easyhtml.dom.HTMLCollection object that contains tags withspecified in the query attributes. The query is a string of pairsattr=value separated by semicolons and any number of spaces. For instance,"attr1=value1; attr2=value2":query: a query string, type strHTMLTag.get_element_by_id(e_id)Returns a tag with specified id. If such tag does not exist returns None.:e_id: an ID of the tag, type strHTMLTag.filter_tags_by_attrs(query)Returns the tag itself if it matches the query, otherwise returns None.The query is a string of pairs attr=value separated by semicolons and anynumber of spaces. For instance, "attr1=value1; attr2=value2":query: a query string, type strclass easyhtml.dom.HTMLDocument()A root document object. Contains all HTML elements and provides an API toaccess them.HTMLDocument Methods:HTMLDocument.raw_htmlA property that returns an HTML code of the document.HTMLDocument.__str__()Returns a str version of the document. It's implicitly called in the strcontext. It consists of the str versions of all contained elements.HTMLDocument.doctypeA property that contains the DoctypeDeclaration object of the document.The property allows to write a new doctype to it.HTMLDocument.inner_htmlA property that returns HTML codes of all contained elements.HTMLDocument.append(element)Adds an element to the end of the list.:element: an element to append, allowed types:easyhtml.dom.HTMLTextNodeeasyhtml.dom.HTMLTageasyhtml.dom.HTMLCommentHTMLDocument.tagsA property that returns a generator object that generates all containedtags of the document.HTMLDocument.get_all_tags()Returns a generator object that generates all contained tags of thedocument including all their nested tags recursively.HTMLDocument.get_tags_by_name(name)Returns an easyhtml.dom.HTMLCollection object contains tags with specifiedname including nested tags. The same functionality is provided by gettingthe tag's name as an attribute: doc.get_tags_by_name("name") = doc.name:name: a name of search tags, type strHTMLDocument.get_children(query)Returns an easyhtml.dom.HTMLCollection object that contains tags withspecified in the query attributes. The query is a string of pairsattr=value separated by semicolons and any number of spaces. For instance,"attr1=value1; attr2=value2":query: a query string, type strHTMLDocument.get_element_by_id(e_id)Returns a tag with specified id. If such tag does not exist returns None.:e_id: an ID of the tag, type strclass easyhtml.dom.HTMLCollection(items)A result object returned by get_* methods. Collection is an object thatcontains found tags or collections of tags.:items: an iterable object contains a content of the collectionThe collection object is iterable and provides the __getitem__ method toaccess its items using [] operator. Also it provides the __len__ methodso len(collection) would return actual count of elements in thecollection.HTMLCollection Methods:HTMLCollection.get_element(index)Returns an element with specified index. If such element does not existNone would be returned. The same functionality is provided by [] operator.:index: an index of the element, type intHTMLCollection.get_tags_by_name(name)Returns an easyhtml.dom.HTMLCollection object contains collections withthe results of such search request to each contained element. The samefunctionality is provided by getting the tag's name as an attribute:collection.get_tags_by_name("name") = collection.name:name: a name of search tags, type strHTMLCollection.get_children(query)Returns an easyhtml.dom.HTMLCollection object that contains collectionswith the results of such search request to each contained element. Thequery is a string of pairs attr=value separated by semicolons and anynumber of spaces. For instance, "attr1=value1; attr2=value2":query: a query string, type strHTMLCollection.filter_tags_by_attrs(query)Filters contained tags or tags in contained collections leaving thosematch specified query. If there is no such tags the collection would beempty. The query is a string of pairs attr=value separated by semicolonsand any number of spaces. For instance, "attr1=value1; attr2=value2"The same functionality is provided by the __call__ method, socollection.filter_tags_by_attrs("attr=value") = collection("attr=value")Note that since the return value of search methods are the HTMLCollectionobject, you could use just document.div("class=foo") instead ofdocument.div.filter_tags_by_attrs("class=foo"):query: a query string, type strHTMLCollection.get_element_by_id(e_id)Returns a tag with specified id. If such tag does not exist returns None.:e_id: an ID of the tag, type str