API Guide
The TorSeeker class
The TorSeeker class provides two methods for querying information about Tor relays: two letter country code, one or multiple Tor IP addresses. Once a query is performed, Tor relays are stored in separate lists based on the type of relay, ie: Guard, Middle or Exit.
Logging is available to display error messages encountered during the process. However, logging is disabled by default. Use the function set_logging() to enable logging if desired.
- param country
optional two letter country code
- type
str
- torseeker.TorSeeker.get_all_relays(self)
Returns a list of TorNode objects for all Tor relay types.
- Returns
a list storing TorNode objects as elements, None otherwise
- Return type
list
- torseeker.TorSeeker.get_exit_relays(self)
Returns a list of TorNode objects for Tor Exit relay types.
- Returns
a list storing TorNode objects as elements
- Return type
list
- torseeker.TorSeeker.get_guard_relays(self)
Returns a list of TorNode objects for Tor Guard relay types.
- Returns
a list storing TorNode objects as elements, None otherwise
- Return type
list
- torseeker.TorSeeker.get_middle_relays(self)
Returns a list of TorNode objects for Tor Middle relay types.
- Returns
a list storing TorNode objects as elements, None otherwise
- Return type
list
- torseeker.TorSeeker.query_relays_by_country(self, country=None)
Query for Tor relays based a two letter country code. This function performs input validation and verifies the two letter country code is valid. If 0 is returned, then the country code specified is invalid or there are no Tor relays located in that country.
- Parameters
country – a two letter country code. This is optional if a country code was defined via the constructor of this class
- Type
str
- Returns
1 on successful query, 0 otherwise
- Return type
int
- torseeker.TorSeeker.query_relays_by_ip(self, ip_addresses=None)
Query for Tor relays based on one or multiple Tor IP addresses. This functions performs input validation to verify that the IP addresses provided are valid IPv4 format. If 0 is returned, then the IP addresses specified are invalid or there are no Tor relays associated with those IP addresses.
- Parameters
ip_addresses – a list of Tor IP addresses
- Type
list
- Returns
1 on successful query, 0 otherwise
- Return type
int
- torseeker.TorSeeker.set_logging(self, state)
Enable logging to stdout.
- Parameters
state – True enables logging, False disables logging
- Type
bool
The TorNode class
The TorNode class defines a Tor relay.
This class provides the ability to parse raw JSON data containing information about a Tor relay. The parse_new_data() function consumes raw JSON data and populates the following members which are accessible via this class:
first_seen - The date and time when the Tor relay was first seen online
last_seen - The date and time the Tor relay was last seen online
last_restarted - The date and time the Tor relay was restarted
country - The two letter country code the Tor relay resides
country_name - The country name the Tor relay resides
nickname - A name assigned to the Tor relay
ipv4 - The IP address version 4
ipv4_port - The port number of the IPv4 address
ipv6 - The IP address version 6
ipv6_port - The port number of the IPv6 address
raw_data - The raw JSON data about the Tor relay
- torseeker.TorNode.parse_raw_data(self, raw_data)
Parse raw JSON data about a given Tor relay.
- Parameters
raw_data – a dictionary containing information about a Tor relay
- Type
dict