Pymerc
A Python library for interacting with the Mercatorio browser based game
Usage
You must first generate API credentials.
Once generated, you can instantiate a Client instance using the credentials.
from pymerc.client import Client
# Create a new client
client = Client(os.environ["API_USER"], os.environ["API_TOKEN"])
Game Objects
The pymerc package provides both low-level API calls as well as high-level objects that wrap those calls.
In almost all cases, you should plan to use the higher-level objects.
If something is missing in one of these objects, please submit an issue or PR.
Most logic is contained within the Player object:
player = await client.player()
Creating the player object can take a few seconds as it results in several requests being sent to the API. It's recommended you re-use the player object instead of recreating it multiple times. The data for the player object can be updated with:
await player.load()
Storehouse
Check our balance of beer and then buy some from the local market:
>>> from pymerc.api.models.common import Item
>>> beer = player.storehouse.items[Item.Beer]
>>> beer.balance
41.5
>>> beer.market_data
TownMarketItem(price=2.894, last_price=2.894, average_price=2.894, moving_average=2.868, highest_bid=2.894, lowest_ask=3.0, volume=95, volume_prev_12=1085, bid_volume_10=2, ask_volume_10=20)
>>> details = await beer.fetch_market_details() # More fine-grained details
>>> details.asks
[ItemOrder(volume=20, price=3.0),
ItemOrder(volume=1, price=3.425),
ItemOrder(volume=3, price=3.475),
ItemOrder(volume=1, price=3.526)]
>>> result = await beer.buy(1, 3.0)
>>> result.settlements[0].volume
1
Adjust the price and volume of beer we are selling:
>>> beer.manager
InventoryManager(buy_price=5.45, buy_volume=0, capacity=100, max_holding=None, sell_price=2.8, sell_volume=25)
>>> await beer.patch_manager(sell_price=2.7, sell_volume=26)
>>> player.storehouse.items[Item.Beer].manager
InventoryManager(buy_price=5.45, buy_volume=0, capacity=100, max_holding=None, sell_price=2.7, sell_volume=26)
Transports
Load the transport that is currently docked in Aderhampton:
>>> tr = player.transports.by_town_name('Aderhampton')[0]
>>> tr.docked
True
List the items we are exporting here:
>>> list(tr.exports.keys())
[<Item.Cloth: 'cloth'>,
<Item.DyedCloth: 'dyed cloth'>,
<Item.Garments: 'garments'>]
Check how much cloth we exported last turn:
>>> tr.exports[Item.Cloth].manager.sell_volume
37
>>> tr.exports[Item.Cloth].volume_flowed
37
Looks like we are at max capacity for our export. Bump our export volume and then buy some more cloth off the Aderhampton market:
>>> await tr.exports[Item.Cloth].patch_manager(sell_volume=38)
>>> details = await tr.exports[Item.Cloth].fetch_market_details()
>>> details.bids
[ItemOrder(volume=1, price=8.99),
ItemOrder(volume=3, price=8.856),
ItemOrder(volume=1, price=8.822),
ItemOrder(volume=1, price=8.478),
ItemOrder(volume=5, price=8.441),
ItemOrder(volume=1, price=5.414)]
>>> player.storehouse.items[Item.Cloth].balance
1477.096
>>> await tr.exports[Item.Cloth].sell(1, 8.99)
>>> player.storehouse.items[Item.Cloth].balance
1476.096
Operations
Get the operations for all of our weaveries:
>>> from pymerc.api.models.common import BuildingType
>>> player.operations.by_building_type(BuildingType.Weavery)
OperationsList([<pymerc.game.operation.Operation at 0x7ffbb00de6f0>])
We have a single operation going on associated with a weavery. Check how much it is currently outputting:
>>> player.operations.by_building_type(BuildingType.Weavery).outputs
{<Item.Cloth: 'cloth'>: 400.0}
Check all of our operations that are taking cloth as an input:
>>> player.operations.by_item_input(Item.Cloth)
OperationsList([<pymerc.game.operation.Operation at 0x7ffbb00debd0>,
<pymerc.game.operation.Operation at 0x7ffbb00dede0>,
<pymerc.game.operation.Operation at 0x7ffbb00dee70>,
<pymerc.game.operation.Operation at 0x7ffbb00dcf80>])
Check how much cloth all of these operations are consuming in total:
>>> player.operations.by_item_input(Item.Cloth).inputs[Item.Cloth]
197.0
Data Analysis
Compare our total and actual imports:
>>> player.imports.volume
426
>>> player.imports.volume_flowed
281 # Importing a little over half of our target volume
>>> player.imports.cost
3669.11
>>> player.imports.cost_flowed
1715.167 # Importing at half of our target cost (yay!)
See how our cloth production is doing:
>>> cloth = player.storehouse.items[Item.Cloth]
>>> cloth.produced
400.0
>>> cloth.production_cost
2383.614
>>> excess = cloth.produced - cloth.consumed
>>> excess_value = excess * cloth.average_cost
>>> value_flowed = cloth.sale_value + player.exports[Item.Cloth].value_flowed
>>> value_flowed > excess_value
False # Looks like we're not making money on our excess cloth!
Testing
Since this library parses live API endpoints, mocking values makes little sense.
Instead, you must provide a .env file with your API credentials:
API_USER="<USER>"
API_TOKEN="<TOKEN>"
The tests will utilize this to validate that all endpoints are parsing correctly:
pytest .
Additionally, you can create an instance of the client/player to test with using ipython:
> ipython
In [1]: from shell import main; await main(); from shell import client;
In [2]: player = await client.player()
Metadata
Release files for pymerc 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pymerc-0.6.0.tar.gz | 27.3 kB | Without provenance | Details for pymerc-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pymerc-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for pymerc-0.6.0-py3-none-any.whl |
Total release size: 64.2 kB
Release files / pymerc-0.6.0.tar.gz
| Download URL | pymerc-0.6.0.tar.gz |
|---|---|
| Size | 27.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5a3c03764d47b4d67d7a374ba47f0b0e52a3dd537d1010d659da0675e1cd3d82
|
|
BLAKE2b-256 checksum How to use checksums |
0754c7ce42801127c06ea3dc1d992c1203f20e8c8398eaa422644b9899aa06b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.0.0 CPython/3.12.3
|
Release files / pymerc-0.6.0-py3-none-any.whl
| Download URL | pymerc-0.6.0-py3-none-any.whl |
|---|---|
| Size | 37.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
16727c81bce07beff4a8a07ab7d0eacb99a51523e228b6d1b3c6632b15218d69
|
|
BLAKE2b-256 checksum How to use checksums |
0cb481c770d64253c93186e6711bf15c4cd822c6bddf538def3ff2829d7c1c9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.0.0 CPython/3.12.3
|
Security for pymerc 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.