Find elements in HTML by matching them with a skeleton
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status PyPI version

ankle is a tool that finds elements inside HTML documents by comparing them with an HTML skeleton. It is useful in testing to check markup returned by a server or possibly web scraping.

Works on Python 2.7 and Python 3.4+.


$ pip install ankle


ankle.find_all(skeleton, document)

Return all elements from document that match given skeleton.

Skeleton elements are compared with the document's by tag name, attributes and text inside or between them.

Children of elements in the skeleton are looked for in the descendants of matching elements in the document.

Order of elements in the skeleton is signficant.

Skeleton must contain one root element.

document and skeleton may be either HTML strings or parsed etrees.

ankle.find(skeleton, document)

Return the first element that matches given skeleton in the document.

ankle.find_iter(skeleton, document)

Return an iterator that yields elements from the document that match given skeleton.

See find_all for details.


  • Class attribute is checked by strict equality, but it may be desirable to ignore classes that aren't present in the skeleton
  • Text inside and between elements is checked strictly, so, for example, if it's broken up by a <span> in the document, but presented without it in the skeleton, it won't be found
  • There are no nice assertion failure messages when using in py.test so it's difficult to see what failed to match and why


import ankle

document = """
		<h1>My document</h1>
			Some text
		<form id="subscription-form">
			<h2>Subscribe for more information!</h2>
			<div class="control-row">
				<label for="email">Email</label>
				<input name="email" placeholder="Email"/>
			<div class="control-row">
				<label for="tos">
					<input name="tos" type="checkbox" class="checkbox-input">
					<span class="checkbox-text">I agree to TOS</span>
			<div class="submit-row">
				<button type="submit">Subscribe</button>

skeleton = """
	Subscribe for more information!
	<label for="email">Email</label>
	<input name="email">
	<label for="tos">
		<input name="tos" type="checkbox">
		I agree to TOS
	<button type="submit"></button>

ankle.find(skeleton, document)  # will return the <form> element from the document