Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

A (somewhat) smart locator class for Selenium.

Project Description


Class encapsulating generating of the Selenium locators.

It is designed to be simple and intuitive to use. It provides you various ways how to generate a Selenium-compatible locators. The class is usable in Selenium element queries.

loc = Locator(By.XPATH, '//foo/bar/baz')    # Old selenium way of doing it
element = s.find_element(*loc)              # Expand the tuple. That's how to use the class.

This is a basic sample of how does it work. Now come the usage samples of simplified locators:

# When you use this simple format of CSS consisting of tag name, ids and classes, it gets
# detected automatically and the result is a CSS selector. IDs and classes are optional.
Locator('')  # => Locator(by='css selector', locator='')
# When you specify a plain string and it does not get matched be the preceeding CSS detector
# it is assumed it is an XPath expression
Locator('//h1') # => Locator(by='xpath', locator='//h1')
# If you pass a Locator instance, it just goes straight through
Locator(Locator('//h1')) # => Locator(by='xpath', locator='//h1')
# If you have your own object, that implements __locator__(), then it can also be resolved
# by the class. The __locator__() must either return Locator instance or
# anything that Locator can process.
# You can leverage kwargs to say strategy=locator
Locator(xpath='//h1')   # => Locator(by='xpath', locator='//h1')
Locator(css='#something')   # => Locator(by='css selector', locator='#something')
Locator(by='xpath', locator='//h1')   # => Locator(by='xpath', locator='//h1')
# For your comfort, you can pass a dictionary, like it was kwargs
Locator({'by': 'xpath', 'locator': '//h1'})   # => Locator(by='xpath', locator='//h1')
# You can also use Locator's classmethods, like this:
Locator.by_css('#foo')   # => Locator(by='css selector', locator='#foo')
# Always in format Locator.by_<strategy_name>

When you have locators, you can avoid using * by using convenience methods:

l = Locator('#foo')
browser = Firefox()
element = l.find_element(browser)
elements = l.find_elements(browser)

As you can see, the number of ways how to specify the input parameters offer you a great freedom on how do you want to structure your locators. You can store them in YAML and you can use Locator to parse the entries. Or anything else.

Available selector strategies:

  • class_name
  • css
  • id
  • link_text
  • name
  • partial_link_text
  • tag
  • xpath


Licensed under GPLv3

Release History

This version
History Node


History Node


History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(19.1 kB) Copy SHA256 Hash SHA256
Source None Apr 7, 2017

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Google Google Cloud Servers