Manager module

socks5man.manager

This module contains the class that can be used to interact with Socks5man from within your script/program. It can acquire, list, add, bulk add, and delete socks5 server.

class socks5man.manager.Manager

A helper class that should be used to interact with Socks5man. All returned socks5 servers will be returned in a socks5man.socks5.Socks5 wrapper. This allows for direct usage of the retrieved information.

acquire(country=None, country_code=None, city=None, min_mbps_down=None, max_connect_time=None, update_usage=True)

Acquire a socks5 server that was tested to be operational. The returned socks5 server will automatically be marked as used. Acquiring is in a round-robin fashion.

Parameters:
  • country – Country the socks5 server should be in.
  • country_code – 2-letter country code (ISO 3166-1 alpha-2).
  • city – City the socks5 server should be in.
  • min_mbps_down – The minimum average download speed in mbits (float).
  • max_connect_time – The maximum average connection time in seconds a socks5 server should have (float).
  • update_usage – Mark retrieved socks5 as used. (bool).
Returns:

A Socks5 object containing information about the server. None if no matching Socks5 server was found.
Return type:

Socks5
Example: 
>>> from socks5man.manager import Manager
>>> Manager().acquire(country="Germany")
add(host, port, username=None, password=None, description=None)

Add a socks5 server.

Parameters:
  • host – IP or a valid hostname of the socks5 server. Should be unique.
  • port – Port of the socks5 server (int)
  • username – Username of the socks5 server (optional)
  • password – Password for the socks5 server user (optional). Password will be stored in plaintext!
  • description – Description to store with the socks5 server (optional)
Returns:

A dictionary containing the provided information, the generated id, the determined country, country code, and city.
Return type:

dict
Raises:

Socks5CreationError
Example: 
>>> from socks5man.manager import Manager
>>> Manager().add("example.com", 8456)
    {
        'username': None,
        'city': u'Norwell',
        'host': 'example.com',
        'country_code': u'US',
        'country': u'United States',
        'password': None,
        'port': 8456,
        'id': 1
    }

Note

It is only possible to provide both a username and a password. Hostname/IP should be unique. If a socks5 exists with the provided hostname/IP, a Socks5CreationError will be thrown.

bulk_add(socks5_dict_list, description=None)

Bulk add multiple socks5 server. No duplicate checking is done.

Parameters:
  • socks5_dict_list – A list of dictionaries that at a minimum contain the keys and valid values for ‘host’ and ‘port’.
  • description – A description to be added to all provided servers
Returns:

The amount of socks5 server that were successfully added
Return type:

int
Raises:

Socks5CreationError
Example: 
>>> from socks5man.manager import Manager
>>> Manager().bulk_add([{"host": "example.com", "port": 1234}, {"host": "example.org", "port": 1234}])
2

Note

It is only possible to provide both a username and a password for a server. Hostname/IP should be unique. Socks5 servers with invalid hostnames or missing fields will be skipped. Socks5CreationError is raised if no valid servers are in the list.

delete(socks5_id)

Delete socks5 with given id

Parameters:socks5_id – A socks5 server id (int)
Example: 
>>> from socks5man.manager import Manager
>>> Manager().delete(1)
delete_all()

Remove all socks5 servers from the database

Example: 
>>> from socks5man.manager import Manager
>>> Manager().delete(1)
list_socks5(country=None, country_code=None, city=None, host=None, operational=None)

Retrieve list of existing socks5 servers using the specified filters. This does not mark them as used. It only retrieves a list of matching servers. Returns an empty list if no matches were found. Returns all servers if no filters were provided.

Parameters:
  • country – Country of a socks5 server
  • country_code – 2-letter country code (ISO 3166-1 alpha-2)
  • city – City of a socks5 server
  • host – The host/IP of a socks5 server
  • operational – Operational or not (bool). Is ignored if value is None
Returns:

A list of Socks5 objects containing the information of the matching servers.
Return type:

list
Example: 
>>> from socks5man.manager import Manager
>>> Manager().list_socks5(country="united states")
[
    <Socks5(host=example.com, port=1234, country=United States, authenticated=False)>,
    <Socks5(host=example.org, port=1234, country=United States, authenticated=False)>
]

>>> Manager().list_socks5()
[
    <Socks5(host=example.com, port=1234, country=United States, authenticated=False)>,
    <Socks5(host=example.org, port=1234, country=United States, authenticated=False)>,
    <Socks5(host=example.net, port=1234, country=Germany, authenticated=False)>
]