Rival-Regions-Wrapper

This library functions as an authenticator and API wrapper for interaction with Rival Regions. Use at your own risk.

Install

This package is available on the Python Package Index (PyPi) under the name rival-regions-wrapper. Use the following command to install the package globaly using pip:

pip install rival_regions_wrapper

When running on local authentication it is also required to have ChromeDriver installed. This to automate browser actions to account login, private-, conference-, and language chat messages.

Alternative when you want to use the development version you can clone the repository localy. Check out the dev branch, then run pip install -e . inside the directory to install the package globaly. It is then possible to edit the source code for development and testing.

Usage

Authentication is done through a middleware module that determines how to send the request. The middleware can also be used to write direct requests to Rival Regions in case the wrapper classes dont suffice. If you are unsure middleware to use, then it is advised to implement LocalAuthentication.

LocalAuthentication is used to login in directly into Rival Regions using supported login methods. When running into issues with login then I would appreciate if you could help me resolve the issue. Available login methods: Google (supported), vk (may work, never tested), facebook (may work, never tested) Use username, password, and login method to log in local instance of the authenticator.

RemoteAuthentication connects through a remote API using URL and authentication key. This is expermental and isn't documentend but I have plans to improve on this in the future.

There is a wrapper available for the following entities: article, conference, craft, language_chat, market, overview, perks, profile, resource_state, storage, war, work For now there is limited documentation how to use the wrapper classes. Read the files here to see how they work.

Problems

This browser or app may not be secure

Probably the most common problems you may encounter will be about authentication your account. In some cases for Google accounts while logging in the browser automation tools are detected. After submitting the google username it gets a prompt that says: "This browser or app may not be secure". To resolve this problem it is required to run the library with the show_window option, when you start the library it will show a Google Chrome window. This is required because you will have to fill in your loggin credentials by yourself. It is only required once, because from then on your Google authentication is saved in the Chrome profile.

1. To start the library with show_window option, add True to the initializing of the LocalAuthentication class, like this: LocalAuthentication(True).
2. Start your application, you will see a Google Chrome window what fills in your username.
3. After submitting your username you see the error message, and a new tab opens.
4. In the new tab log into your Google account.
5. After sucessfully loggin in wait until Google Chrome closes.

From now on you should be able to use your Google account with the library without a problem. You can disable the library show_window option by removing True when calling the LocalAuthentication.

When you face this issue on a headless server it can be solved by copying the Google Chrome profile from your local machine to the server. The profile is located in the following directory on Linux: ~/.local/share/rival_regions_wrapper/chrome/.

Captcha

When loggin in to your Google account makes you fill out a captcha you can use anti-captcha service to circumvent them. Put the key into the LocalAuthenticator after the show_window option, like this: LocalAuthentication(False, <ant_captcha_key>).

Examples

Create LocalAuthentication middleware and log in using environ variables.

import os
from rival_regions_wrapper.middleware import LocalAuthentication

authentication = LocalAuthentication()
authentication.set_credentials(
  os.environ["USERNAME"],
  os.environ["PASSWORD"],
  os.environ["LOGIN_METHOD"]
)

request region page from Rival Regions.

region = authentication.get('listed/upgrades/{}'.format(region_id))

Example of API wrapper to get oil current available resources from a state.

from rival_regions_wrapper.wrapper import ResourceState

state = 3382
resource = 'oil'
response = ResourceState(authentication, state).info(resource)

For more examples look at the unit tests.

Testing

This libary supports unit tests, these can be found in rival_regions_wrapper/tests/. To run them besides, Pip it is also required to install Pipenv. Clone the repository localy, then intall required development dependencies using pipenv install --dev. After installing these packages, you are able to run the tests with the pytest command.

Requests are cached for quick testing using VCR.py located at rival_regions_wrapper/tests/cassettes/. If you run in problems with testing you are advised to them run again after removing the cassettes directory. Use the parameter --disable-vcr to disable VCR temporaly when running Pytest.

The tests read login credentials and other information from the following environment variables: USERNAME, PASSWORD, and LOGIN_METHOD. You can set those variables by copying example.env to .env. Replace PLACEHOLDER` with your credentials.

Required environ variables:

USERNAME=PLACEHOLDER
PASSWORD=PLACEHOLDER
LOGIN_METHOD=PLACEHOLDER

There are several optional environ variables, as you can see here with some example value.

CAPTCHA_KEY=59f34d451658f55a517eb1395df52331f
CONFERENCE_ID=439289
CONFERENCE_TITLE=test
LANGUAGE_CHAT=da
PERK=strenght
PERK_UPGRADE_TYPE=gold
CRAFT_ITEM=energy_drink
CRAFT_AMOUNT=10
PROFILE_ID=2000340574
MESSAGE=test

In case you want to use the anti-caption service you can fill in the key in CAPTCHA_KEY. Other variables are required to run test that are skipped by default. These test are skipped because the test sends out a request that makes change to Rival Regions, like sending messages, or crafting items. You can run those these test by changing the appropiate environ variable and adding the --no-skip parameter. When using this parameter it is advised to specify which test to run. This can be done with the -k parameter, for example pytest -k profile_message --disable-vcr --no-skips. To get a more verbose output from Pytest, use the -v parameter. To see log output of library use the -s parameter.

Contact

• Discord