rival_regions_wrapper/README.md

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.

Examples

Create LocalAuthentication middleware and log in with using environ variables.

import os
from rival_regions_wrapper.middleware import LocalAuthentication

authentication = LocalAuthentication(
  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. ReplacePLACEHOLDER` 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