From 8fe34b2650a1be83cb3e99085e2f300caab54063 Mon Sep 17 00:00:00 2001 From: NW/RL Date: Sat, 13 Apr 2024 22:26:07 -0500 Subject: Make documentation look significantly better --- README.md | 156 +++++++++++++++++++++----------------------------------------- 1 file changed, 52 insertions(+), 104 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 615fb9a..ec20343 100644 --- a/README.md +++ b/README.md @@ -24,132 +24,80 @@ If using [Poetry](https://python-poetry.org/), all Python dependencies are fetch 1. In a poetry shell, run `poetry add steamrelationships` 2. Import the package `import steamrelationships` -3. Create an object (example: `steamuser: object = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")`) -4. Do a scan (example: `results = steamuser.basic_scan("XXXXXXXXXXXXXXXXX")`) - -Example: - -```python -#!/usr/bin/env -S python3 -i - -# A program that finds the friendliest person in a user's extended friend's list (1 recursive scan) - -import steamrelationships - -if __name__ == "__main__": - rq = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", reqsafetybuffer=0.01) - testlist = rq.recursivescan("XXXXXXXXXXXXXXXXX", recurselevel=1) - del rq - - friendliest: str = "" - mostfriends: int = 0 - for person in testlist: - if len(testlist[person]) >= mostfriends: - mostfriends = len(testlist[person]) - friendliest = person - - print(f"Largest friends list: {mostfriends}, Owned by: {friendliest}") -``` +3. See the documentation on methods & objects ## DOCUMENTATION -```python -''' -CONSTANTS: - Define a constants object: - - from steamrelationships.constants import _Const - CONST = _Const() - - CONST.STEAMAPI_MAXREQ = 100000 - # Steam's daily API request limit +### Objects - CONST.DAY_IN_NANO = (8.64 * (10 ** 13)) - # The number of nanoseconds in a day +| Object | Full Name | Description | +| :----: | :-------: | :---------- | +| SteamRelationships | steamrelationships.sr.SteamRelationships | A class implementing Steam friends list scanning | +| Object | steamrelationships.constants._Const | A class containing constant values used throughout the SteamRelationships Class | - CONST.JSON_INDENT = 4 - # The indent used when dumping a python object to json -''' +### Constants -# Example -import time -from steamrelationships.constants import _Const -CONST = _Const() - -checktime = time.time_ns() -oldtime = int(input("Enter a time since the Unix Epoch in nanoseconds: ")) -if checktime - oldtime > CONST.DAY_IN_NANO: - print("It has been at least 1 day since the entered time") - - - -''' -STEAMRELATIONSHIPS: - Create a SteamRelationships object: - import steamrelationships - steamuser: object = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX") - - basicscan - do a basic scan of someone's steam friends - PARAMS: - (str) steamid64 - The 64 bit steam id of the user you want to scan +| Name | Value | Description | +| :-- | ---: | ----------- | +| STEAMAPI_MAXREQ | 100000 | Steam's daily API request limit | +| DAY_IN_NANO | 8.64 * (10 ** 13) | The amount of nanoseconds in 24 hours | +| JSON_INDENT | 4 | The indent used when dumping a Python object to a .json file | - RETURN VALUES: - (dict) EMPTY - There was an error scanning the user's friends list - (dict) {steamid64: [friendID1, friendID2, ...]} - A dict with a single key, that of the scanned user, which maps to a list of the users's friends +### `steamrelationships.sr.SteamRelationships()` methods +| Function | Params | Return Values | Description | +| :------: | :----- | :------------ | :---------- | +| basicscan | **`(str) steamid64`** - A 64 bit decimal Steam id | **`(dict)`** A dict with a single key, that of the scanned user, which maps to a list of the users's friends. **Empty on error** | Send a request to Steam's API to retrieve a specified user's friends list | +| recursivescan | **`(str) steamid64`** - A 64 bit decimal Steam id; **`(int, Default = 2) recurselevel`** - The number of recursive scans to complete | **`(dict)`** A dict containing the starting steamid, then the friends contained in the original scan with the results of their scan. **Empty on error** | Scan a person's friends list, then scan for their friends' lists. This process repeats for every level of "`recurselevel`" | +
- recursivescan - Scan a user's friends list, then scan their friends as well +Private steamrelationships.sr.SteamRelationships() methods - PARAMS: - (str) steamid64 - The starting user to scan - (int) recurselevel - The number of recursive scans to complete - > Note: 0 is equivalent to a basic scan; 1 scans the specified user, then the user's friends; etc. +### Private `steamrelationships.sr.SteamRelationships()` methods - RETURN VALUES: - (dict) EMPTY - Some catastrophic error has occured and no scan could be started - (dict) { - steamid64: - [friend1id, friend2id, friend3id, ...], - friend1id: - [other_friend, other_friend, ...], - friend2id: - [other_friend, other_friend, ...], - friend3id: - [other_friend, other_friend, ...], - ... - } +| Function | Params | Return Values | Description | +| :------: | :----- | :------------ | :---------- | +| __readjsonfile | **`(str) filepath`** - Path to json file | **`(dict)`** The contents of the json file. **Empty on error** | Read the specified json file for previous requests. Will create an "empty" json file if the specified file at the `filepath` doesn't exist | +| __checkrequests | **`(str) filename`** - filepath to requests log | **`(int)`** The number of requests in the last 24 hours. **`-1` on error**, `0` *on too many requests*, and `>1` if a valid number of requests | Check the requests log to make sure Steam's request limit hasn't been passed. Will create a file at `filepath` if it doesn't exist, also will *never go over 100,000 requests*, regardless of what `reqsafetybuffer` is | +| __getFriendsList | **`(str) steamid64`** - A Steam User's id, in the steamid64 format; **`(int, Default = 0) _retries`** - An internal value used to limit the number of retries after a timeout. Increments by one automatically on every timeout | **`(dict)`** The json representation of Steam's response. **Empty on error** | Send a request to the Steam Web API to get a user's friends list | +| __parseFriendsList | **`(dict) friendsdict`** - The return value of `__getFriendsList` | **`(list)`** The steamid64's of a user's friends. **Empty on error** | Parse a response from Steam and extract a user's friend's Steam IDs | - - A dict containing the starting steamid, then the friends contained in the original scan with the results of their scan +
- NOTE: - Please do not use a value greater than 3. While theoretically any value works, due to the exponential nature of friendship relations, you will very quickly spam Steam with tens of thousands of requests. If this concept is unfamiliar to you, please take a quick glance at the Wikipedia page for "six degress of separation": https://en.wikipedia.org/wiki/Six_degrees_of_separation +Example program - TLDR: recursivescan is exponential and you will reach 100,000 requests very quickly if you recurse greater than 3 -''' +```python +#!/usr/bin/env -S python3 -i -# Example import steamrelationships +from steamrelationships.constants import _Const +CONST = _Const() + +if __name__ == "__main__": + print(f"Constants:\n\t> Max API Requests per Day: {CONST.STEAMAPI_MAXREQ}\n\t> Number of Nanoseconds In a Day: {CONST.DAY_IN_NANO}\n\t> .json File Indent: {CONST.JSON_INDENT}") -steamuser: object = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX") + # Replace the XXXX's with your dev api key + steamuser: object = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", reqsafetybuffer=0.01) -bigscan: dict = steamuser.recursivescan("XXXXXXXXXXXXXXXXX") -littlescan: dict = steamuser.basicscan("XXXXXXXXXXXXXXXXX") + # Replace the XXXX's with the steam id of the guy you want to scan + bigscan: dict = steamuser.recursivescan("XXXXXXXXXXXXXXXXX", recurselevel=1) + littlescan: dict = steamuser.basicscan("XXXXXXXXXXXXXXXXX") -del steamuser + del steamuser -print(f'Original scanned user: {list(littlescan.keys())[0]}\nOriginal Friends: {littlescan[list(littlescan.keys())[0]]}') + print(f'Original scanned user: {list(littlescan.keys())[0]}\nOriginal Friends: {littlescan[list(littlescan.keys())[0]]}') -totalscanned: int = 0 -alreadyscanned: list = [] -for scanned in bigscan.keys(): - totalscanned += 1 - alreadyscanned.append(scanned) + totalscanned: int = 0 + alreadyscanned: list = [] + for scanned in bigscan.keys(): + totalscanned += 1 + alreadyscanned.append(scanned) - for friend in bigscan[scanned]: - if friend not in alreadyscanned: - totalscanned += 1 - alreadyscanned.append(friend) + for friend in bigscan[scanned]: + if friend not in alreadyscanned: + totalscanned += 1 + alreadyscanned.append(friend) -print(f"Total scanned: {totalscanned}") + print(f"Total users found: {totalscanned}") ``` -- cgit v1.2.3