Skip to main content

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)

Source distribution for pymerc 0.6.0
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)

Table of built distributions (wheels) for pymerc 0.6.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page