summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md156
1 files changed, 52 insertions, 104 deletions
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
24 24
251. In a poetry shell, run `poetry add steamrelationships` 251. In a poetry shell, run `poetry add steamrelationships`
262. Import the package `import steamrelationships` 262. Import the package `import steamrelationships`
273. Create an object (example: `steamuser: object = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")`) 273. See the documentation on methods & objects
284. Do a scan (example: `results = steamuser.basic_scan("XXXXXXXXXXXXXXXXX")`)
29
30Example:
31
32```python
33#!/usr/bin/env -S python3 -i
34
35# A program that finds the friendliest person in a user's extended friend's list (1 recursive scan)
36
37import steamrelationships
38
39if __name__ == "__main__":
40 rq = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", reqsafetybuffer=0.01)
41 testlist = rq.recursivescan("XXXXXXXXXXXXXXXXX", recurselevel=1)
42 del rq
43
44 friendliest: str = ""
45 mostfriends: int = 0
46 for person in testlist:
47 if len(testlist[person]) >= mostfriends:
48 mostfriends = len(testlist[person])
49 friendliest = person
50
51 print(f"Largest friends list: {mostfriends}, Owned by: {friendliest}")
52```
53 28
54## DOCUMENTATION 29## DOCUMENTATION
55 30
56```python 31### Objects
57'''
58CONSTANTS:
59 Define a constants object:
60
61 from steamrelationships.constants import _Const
62 CONST = _Const()
63
64 CONST.STEAMAPI_MAXREQ = 100000
65 # Steam's daily API request limit
66 32
67 CONST.DAY_IN_NANO = (8.64 * (10 ** 13)) 33| Object | Full Name | Description |
68 # The number of nanoseconds in a day 34| :----: | :-------: | :---------- |
35| SteamRelationships | steamrelationships.sr.SteamRelationships | A class implementing Steam friends list scanning |
36| Object | steamrelationships.constants._Const | A class containing constant values used throughout the SteamRelationships Class |
69 37
70 CONST.JSON_INDENT = 4 38### Constants
71 # The indent used when dumping a python object to json
72'''
73 39
74# Example 40| Name | Value | Description |
75import time 41| :-- | ---: | ----------- |
76from steamrelationships.constants import _Const 42| STEAMAPI_MAXREQ | 100000 | Steam's daily API request limit |
77CONST = _Const() 43| DAY_IN_NANO | 8.64 * (10 ** 13) | The amount of nanoseconds in 24 hours |
78 44| JSON_INDENT | 4 | The indent used when dumping a Python object to a .json file |
79checktime = time.time_ns()
80oldtime = int(input("Enter a time since the Unix Epoch in nanoseconds: "))
81if checktime - oldtime > CONST.DAY_IN_NANO:
82 print("It has been at least 1 day since the entered time")
83
84
85
86'''
87STEAMRELATIONSHIPS:
88 Create a SteamRelationships object:
89 import steamrelationships
90 steamuser: object = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
91
92 basicscan - do a basic scan of someone's steam friends
93 PARAMS:
94 (str) steamid64 - The 64 bit steam id of the user you want to scan
95 45
96 RETURN VALUES: 46### `steamrelationships.sr.SteamRelationships()` methods
97 (dict) EMPTY - There was an error scanning the user's friends list
98 (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
99 47
48| Function | Params | Return Values | Description |
49| :------: | :----- | :------------ | :---------- |
50| 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 |
51| 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`" |
100 52
53<details>
101 54
102 recursivescan - Scan a user's friends list, then scan their friends as well 55<summary>Private steamrelationships.sr.SteamRelationships() methods</summary>
103 56
104 PARAMS: 57### Private `steamrelationships.sr.SteamRelationships()` methods
105 (str) steamid64 - The starting user to scan
106 (int) recurselevel - The number of recursive scans to complete
107 > Note: 0 is equivalent to a basic scan; 1 scans the specified user, then the user's friends; etc.
108 58
109 RETURN VALUES: 59| Function | Params | Return Values | Description |
110 (dict) EMPTY - Some catastrophic error has occured and no scan could be started 60| :------: | :----- | :------------ | :---------- |
111 (dict) { 61| __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 |
112 steamid64: 62| __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 |
113 [friend1id, friend2id, friend3id, ...], 63| __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 |
114 friend1id: 64| __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 |
115 [other_friend, other_friend, ...],
116 friend2id:
117 [other_friend, other_friend, ...],
118 friend3id:
119 [other_friend, other_friend, ...],
120 ...
121 }
122 65
123 - A dict containing the starting steamid, then the friends contained in the original scan with the results of their scan 66</details>
124 67
125 NOTE: 68Example program
126 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
127 69
128 TLDR: recursivescan is exponential and you will reach 100,000 requests very quickly if you recurse greater than 3 70```python
129''' 71#!/usr/bin/env -S python3 -i
130 72
131# Example
132import steamrelationships 73import steamrelationships
74from steamrelationships.constants import _Const
75CONST = _Const()
76
77if __name__ == "__main__":
78 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}")
133 79
134steamuser: object = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX") 80 # Replace the XXXX's with your dev api key
81 steamuser: object = steamrelationships.SteamRelationships(webapikey="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", reqsafetybuffer=0.01)
135 82
136bigscan: dict = steamuser.recursivescan("XXXXXXXXXXXXXXXXX") 83 # Replace the XXXX's with the steam id of the guy you want to scan
137littlescan: dict = steamuser.basicscan("XXXXXXXXXXXXXXXXX") 84 bigscan: dict = steamuser.recursivescan("XXXXXXXXXXXXXXXXX", recurselevel=1)
85 littlescan: dict = steamuser.basicscan("XXXXXXXXXXXXXXXXX")
138 86
139del steamuser 87 del steamuser
140 88
141print(f'Original scanned user: {list(littlescan.keys())[0]}\nOriginal Friends: {littlescan[list(littlescan.keys())[0]]}') 89 print(f'Original scanned user: {list(littlescan.keys())[0]}\nOriginal Friends: {littlescan[list(littlescan.keys())[0]]}')
142 90
143totalscanned: int = 0 91 totalscanned: int = 0
144alreadyscanned: list = [] 92 alreadyscanned: list = []
145for scanned in bigscan.keys(): 93 for scanned in bigscan.keys():
146 totalscanned += 1 94 totalscanned += 1
147 alreadyscanned.append(scanned) 95 alreadyscanned.append(scanned)
148 96
149 for friend in bigscan[scanned]: 97 for friend in bigscan[scanned]:
150 if friend not in alreadyscanned: 98 if friend not in alreadyscanned:
151 totalscanned += 1 99 totalscanned += 1
152 alreadyscanned.append(friend) 100 alreadyscanned.append(friend)
153 101
154print(f"Total scanned: {totalscanned}") 102 print(f"Total users found: {totalscanned}")
155``` 103```
generated by cgit v1.2.3 (git 2.39.1) at 2025-12-06 04:59:34 +0000