From 320c1b1c619bd1386af7c87463e8658e2397cfbb Mon Sep 17 00:00:00 2001 From: Joey Hines Date: Wed, 2 Jan 2019 17:17:53 -0600 Subject: [PATCH] Added docstrings to all the commands --- api/commands.py | 230 +++++++++++++++++++++++++++++++++--------- docs/source/conf.py | 2 +- docs/source/index.rst | 2 +- 3 files changed, 187 insertions(+), 47 deletions(-) diff --git a/api/commands.py b/api/commands.py index 7e0c2a6..5aa7c42 100644 --- a/api/commands.py +++ b/api/commands.py @@ -69,30 +69,6 @@ def get_location(owner, name=None, loc_type=Location): return loc -@command("POST") -def register(player_name, discord_uuid): - ''' - Register Command - :param player_name: - :param discord_uuid: - :return: - ''' - mc_uuid = grab_UUID(player_name) - player = Player.objects.create(name=player_name, mc_uuid=mc_uuid, discord_uuid=discord_uuid) - - return player.json - - -@command("POST") -def add_base(x_pos, z_pos, name=None, discord_uuid=None, mc_uuid=None): - return add_location(x_pos, z_pos, name=name, discord_uuid=discord_uuid, mc_uuid=mc_uuid, loc_type=Base) - - -@command("POST") -def add_shop(x_pos, z_pos, name=None, discord_uuid=None, mc_uuid=None): - return add_location(x_pos, z_pos, name=name, discord_uuid=discord_uuid, mc_uuid=mc_uuid, loc_type=Shop) - - def add_location(x_pos, z_pos, name=None, discord_uuid=None, mc_uuid=None, loc_type=Location): player = get_player(discord_uuid, mc_uuid) try: @@ -109,11 +85,69 @@ def add_location(x_pos, z_pos, name=None, discord_uuid=None, mc_uuid=None, loc_t else: raise DataBaseError - return location + return location.json + + +@command("POST") +def register(player_name, discord_uuid): + ''' + :request: POST + :param player_name: Minecraft in-game name + :param discord_uuid: Discord UUID if registering from Discord + :return: JSON representation of the new Player + :help: Registers your Discord and Minecraft account with the the database + ''' + + mc_uuid = grab_UUID(player_name) + player = Player.objects.create(name=player_name, mc_uuid=mc_uuid, discord_uuid=discord_uuid) + + return player.json + + +@command("POST") +def add_base(x_pos, z_pos, name=None, discord_uuid=None, mc_uuid=None): + ''' + :request: POST + :param x_pos: MC X Coordinate + :param z_pos: MC Z Coordinate + :param name: Base Name (If None, Defaults to Player's Base) + :param discord_uuid: Discord UUID + :param mc_uuid: Minecraft UUID + :return: JSON representation of the new base + :help: Adds your base to the database. The base name is optional if this is your first base + ''' + + return add_location(x_pos, z_pos, name=name, discord_uuid=discord_uuid, mc_uuid=mc_uuid, loc_type=Base) + + +@command("POST") +def add_shop(x_pos, z_pos, name=None, discord_uuid=None, mc_uuid=None): + ''' + :request: POST + :param x_pos: MC X Coordinate + :param z_pos: MC Z Coordinate + :param name: Shop Name (If None, Defaults to Player's Shop) + :param discord_uuid: Discord UUID + :param mc_uuid: Minecraft UUID + :return: JSON representation of the new shop + :help: Adds your shop to the database. The name is optional if this is your first shop + ''' + + return add_location(x_pos, z_pos, name=name, discord_uuid=discord_uuid, mc_uuid=mc_uuid, loc_type=Shop) @command("POST") def add_tunnel(tunnel_direction, tunnel_number, location_name=None, discord_uuid=None, mc_uuid=None): + ''' + :request: POST + :param tunnel_direction: Tunnel Direction + :param tunnel_number: Tunnel Coordinate + :param location_name: Name of the Location to attach the tunnel to + :param discord_uuid: Discord UUID + :param mc_uuid: Minecraft UUID + :return: JSON Representation of the Tunnel + :help: Adds your tunnel to the database. If you only have one location, you do not need to specify a location name + ''' player = get_player(discord_uuid, mc_uuid) if location_name is None: loc = get_location(player, name=location_name) @@ -127,6 +161,12 @@ def add_tunnel(tunnel_direction, tunnel_number, location_name=None, discord_uuid @command("GET") def find_location(search): + ''' + :request: GET + :param search: Location name or owner to search for + :return: List of the matching locations + :help: Finds all the locations matching the search term + ''' limit = 25 locations = Location.objects.filter(Q(name__icontains=search) | Q(owner__name__icontains=search)).all()[:limit] @@ -139,12 +179,30 @@ def find_location(search): @command("DELETE") def delete(name, discord_uuid=None, mc_uuid=None): + ''' + :request: DELETE + :param name: Name of location to delete + :param discord_uuid: Discord UUID + :param mc_uuid: Minecraft UUID + :return: Location Name + :help: Deletes a location from the database + ''' owner = get_player(discord_uuid, mc_uuid) Location.objects.get(name__iexact=name, owner=owner).delete() + return name @command("GET") def find_around(x_pos, z_pos, radius=200): + ''' + :request: GET + :param x_pos: MC X Coordinate + :param z_pos: MC Z Coordinate + :param radius: Radius to each around (default 200) + :return: List of all locations in the radius + :help: Finds all the locations around a certain point + ''' + locations = Location.objects.filter(x_coord__range=(x_pos - radius, x_pos + radius), z_coord__range=(z_pos - radius, z_pos + radius)).all() @@ -153,6 +211,18 @@ def find_around(x_pos, z_pos, radius=200): @command("POST") def add_item(item_name, quantity, diamond_price, shop_name=None, discord_uuid=None, mc_uuid=None): + ''' + :request: POST + :param item_name: name of the item + :param quantity: number of items being sold + :param diamond_price: price in diamonds + :param shop_name: Name of the shop, can be blank if the user only has one shop + :param discord_uuid: Discord UUID + :param mc_uuid: Minecraft UUID + :return: Item Listing + :help: Adds an item to a shop's inventory. If you have one shop, the shop name is not required + ''' + player = get_player(discord_uuid, mc_uuid) shop = get_location(player, shop_name, Shop).shop @@ -165,36 +235,51 @@ def add_item(item_name, quantity, diamond_price, shop_name=None, discord_uuid=No # TODO Re-implement selling shop search @command("GET") def selling(item_name): - items = [] - if len(item_name) == 0: - raise EmptryString + ''' + :request: GET + :param item_name: Item name to search for + :return: List of top matches shop, sorted by when they were added + :help: List shops selling an item. Sorted by most recently added + ''' - shops = ItemListing.objects.annotate(normalized_price=F('price') / F('amount'))\ - .filter(item_name__icontains=item_name).order_by('normalized_price').values('shop_id').distinct() + items = [] + if len(item_name) == 0: + raise EmptryString - if len(shops) == 0: - raise ItemNotFound + shops = ItemListing.objects.annotate(normalized_price=F('price') / F('amount')) \ + .filter(item_name__icontains=item_name).order_by('normalized_price').values('shop_id').distinct() - for shop_id in shops: - shop = Shop.objects.get(pk=shop_id['shop_id']).json + if len(shops) == 0: + raise ItemNotFound - item_query = ItemListing.objects.annotate(normalized_price=F('price') / F('amount')) \ - .filter(item_name__icontains=item_name, shop_id=shop_id['shop_id']) \ - .order_by('normalized_price') \ - .values("item_name", "price", "amount") + for shop_id in shops: + shop = Shop.objects.get(pk=shop_id['shop_id']).json - item_list = [] - for item in item_query: - item_list.append(item) + item_query = ItemListing.objects.annotate(normalized_price=F('price') / F('amount')) \ + .filter(item_name__icontains=item_name, shop_id=shop_id['shop_id']) \ + .order_by('normalized_price') \ + .values("item_name", "price", "amount") - shop["items"] = item_list - items.append(shop) + item_list = [] + for item in item_query: + item_list.append(item) - return items + shop["items"] = item_list + items.append(shop) + + return items @command("GET") def info(location_name): + ''' + :request: GET + :param location_name: Name of the location to get info on + :return: JSON representation of location + :raise LocationLookupError: If no location is found + :help: Finds all the locations matching the search term + ''' + location = Location.objects.get(name__iexact=location_name) if location is None: @@ -208,6 +293,13 @@ def info(location_name): @command("GET") def tunnel(player_name): + ''' + :request: GET + :param player_name: MC player name + :return: List of all the tunnels a user owns + :help: Finds all the tunnels a player owns + ''' + tunnels = Tunnel.objects.filter(location__owner__name__icontains=player_name).all() if len(tunnels) == 0: @@ -218,6 +310,16 @@ def tunnel(player_name): @command("POST") def edit_pos(x, z, loc_name, discord_uuid=None, mc_uuid=None): + ''' + :request: POST + :param x: New MC X coordinate + :param z: New MC Z Coordinate + :param loc_name: Location Name to edit + :param discord_uuid: Discord UUID + :param mc_uuid: MC UUID + :return: Edited Location + :help: Edits the position of a location + ''' player = get_player(discord_uuid=discord_uuid, mc_uuid=mc_uuid) location = get_location(player, loc_name) @@ -226,11 +328,22 @@ def edit_pos(x, z, loc_name, discord_uuid=None, mc_uuid=None): location.z_coord = z location.save() - return location.json + return location.jsone @command("POST") def edit_tunnel(tunnel_direction, tunnel_number, loc_name, discord_uuid=None, mc_uuid=None): + ''' + :request: POST + :param tunnel_direction: New Tunnel Direction + :param tunnel_number: New Tunnel Address + :param loc_name: Location Name to edit + :param discord_uuid: Discord UUID + :param mc_uuid: Minecraft UUID + :return: Edited Location + :help: Edits the tunnel of a location + ''' + player = get_player(discord_uuid=discord_uuid, mc_uuid=mc_uuid) location = get_location(player, loc_name) @@ -245,6 +358,16 @@ def edit_tunnel(tunnel_direction, tunnel_number, loc_name, discord_uuid=None, mc @command("POST") def edit_name(new_name, loc_name, discord_uuid=None, mc_uuid=None): + ''' + :request: POST + :param new_name: New Location Name + :param loc_name: Old Location name + :param discord_uuid: Discord UUID + :param mc_uuid: MC UUID + :return: Edited Location + :help: Edits the name of a location + ''' + player = get_player(discord_uuid=discord_uuid, mc_uuid=mc_uuid) location = get_location(player, loc_name) @@ -256,6 +379,15 @@ def edit_name(new_name, loc_name, discord_uuid=None, mc_uuid=None): @command("DELETE") def delete_item(item, shop_name, discord_uuid=None, mc_uuid=None): + ''' + :request: DELETE + :param item: Item name to delete + :param shop_name: Shop selling item, can be None if the user only has one shop + :param discord_uuid: Discord UUID + :param mc_uuid: Minecraft UUID + :return: Deletes an item from the database + ''' + player = get_player(discord_uuid=discord_uuid, mc_uuid=mc_uuid) shop = get_location(player, shop_name, Shop) @@ -267,6 +399,14 @@ def delete_item(item, shop_name, discord_uuid=None, mc_uuid=None): @command("GET") def me(discord_uuid=None, mc_uuid=None): + ''' + :request: GET + :param discord_uuid: Discord UUID + :param mc_uuid: MC UUID + :return: Returns a list of all the locations owned by a user + :help: Find all the locations in the database + ''' + player = get_player(discord_uuid=discord_uuid, mc_uuid=mc_uuid) locations = Location.objects.filter(owner=player).all() diff --git a/docs/source/conf.py b/docs/source/conf.py index f8a3ac7..a51e05d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -80,7 +80,7 @@ pygments_style = None # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/source/index.rst b/docs/source/index.rst index 130124a..bc96601 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,4 +13,4 @@ goods. :maxdepth: 1 :caption: Contents: - commands + commands \ No newline at end of file