add documentation and examples

sgtpepperpt · Feb 26, 2024 · 34979b2 · 34979b2
1 parent 09796bb
commit 34979b2
Show file tree

Hide file tree

Showing 4 changed files with 167 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -6,18 +6,28 @@ Retrieves static data about lines, stops, locations, and real-time estimates of
 
 Since it's based on a non-official API, it may stop working in the future. Confirmed working as of 24 February 2024.
 
-See the file at `stcp/api.py` for the complete documentation.
+See the files at [stcp/api.py](stcp/api.py) and [stcp/util.py](stcp/util.py) for the complete documentation,
+and [examples.md](examples.md) for usage examples.
 
 ## Available operations
 
 | **Function**          | **Description**                                                                                    |
 |-----------------------|----------------------------------------------------------------------------------------------------|
-| _get_lines_           | gets a list of all STCP lines                                                                      |
+| _get_lines_           | gets a list of all STCP lines.                                                                     |
 | _get_line_directions_ | gets a list of directions (usually 2) of a line.                                                   |
 | _get_line_stops_      | gets a list of all stops of a line.                                                                |
 | _get_stop_data_       | gets information about a stop, including a list of all the lines that pass through it.             |
 | _get_stop_real_times_ | gets a real-time list of buses passing through a stop soon (up to one hour from the current time). |
 
+## Utilities
+
+| **Function**      | **Description**                                               |
+|-------------------|---------------------------------------------------------------|
+| _get_all_stops_   | gets a set of all STCP stop codes across all lines.           |
+| _stop_departures_ | gets a map of upcoming departures of a stop, grouped by line. |
+| _follow_line_     | gets the current times for a given line.                      |
+
+
 ## Notes
 
 To be able to get a stop's real-time departures, a "hash" is needed, which can be obtained by scraping STCP's webpage.

diff --git a/examples.md b/examples.md
@@ -0,0 +1,149 @@
+# API examples
+
+## _get_lines()_
+```PYTHON
+from stcp.api import get_lines
+all_lines = get_lines()
+```
+
+### Result
+```JSON
+[
+    {'line_code': '200', 'accessibility': 1, 'description': '200 - BOLHÃO-CAST. QUEIJO'}, 
+    {'line_code': '201', 'accessibility': 2, 'description': '201 - ALIADOS-VISO'}, 
+    {'line_code': '202', 'accessibility': 2, 'description': '202 - ALIADOS-PASSEIO ALEGRE (VIA AV. BESSA)'}, 
+    {'line_code': '203', 'accessibility': 2, 'description': '203 - MARQUÊS - CAST.QUEIJO'}, 
+    {'line_code': '204', 'accessibility': 1, 'description': '204 - HOSPITAL DE S.JOÃO - FOZ'},
+    ...
+]
+```
+
+---
+
+## _get_line_directions(line_code)_
+```PYTHON
+from stcp.api import get_line_directions
+line_directions = get_line_directions('903')
+```
+
+### Result
+```JSON
+[
+    {'description': 'BOAVISTA-VILAR DO PARAÍSO', 'direction_code': 0, 'readable': '903 VILAR DO PARAÍSO'}, 
+    {'description': 'VILAR DO PARAÍSO-BOAVISTA', 'direction_code': 1, 'readable': '903 BOAVISTA'}
+]
+```
+
+---
+
+## _get_line_stops(line_code, direction_code)_
+```PYTHON
+from stcp.api import get_line_stops
+line_stops = get_line_stops('903', '0')
+```
+
+### Result
+```JSON
+[
+    {'stop_code': 'CMS2', 'name': 'CASA DA MÚSICA (METRO)', 'zone': 'PRT1', 'address': 'CASA DA MÚSICA', 'seq': 1},
+    {'stop_code': 'BCM5', 'name': 'BOAVISTA-CASA DA MÚSICA', 'zone': 'PRT1', 'address': 'AV.FRANÇA', 'seq': 2}, 
+    {'stop_code': 'BS8', 'name': 'BOM SUCESSO', 'zone': 'PRT1', 'address': 'LGO.FERREIRA LAPA', 'seq': 3}, 
+    {'stop_code': 'PRG3', 'name': 'PR. DA GALIZA', 'zone': 'PRT1', 'address': 'PR.GALIZA', 'seq': 4},
+    {'stop_code': 'JM1', 'name': 'JUNTA MASSARELOS', 'zone': 'PRT1', 'address': 'R.CAMPO ALEGRE', 'seq': 5},
+    ...
+]
+```
+---
+
+## _get_stop_data(stop_code)_
+```PYTHON
+from stcp.api import get_stop_data
+stop_data = get_stop_data('TRD1')
+```
+
+### Result
+```JSON
+{
+    'stop_code': 'TRD1',
+    'name': 'TRINDADE', 
+    'zone': 'PRT1', 
+    'address': 'R.TRINDADE', 
+    'mode': 1, 
+    'lon': -8.609555606679713, 
+    'lat': 41.15179869985508, 
+    'lines': [
+        {'line_code': '200', 'direction_code': 1, 'accessibility': 1, 'description': 'BOLHÃO'},
+        {'line_code': '304', 'direction_code': 0, 'accessibility': 2, 'description': 'STA. LUZIA'},
+        {'line_code': '600', 'direction_code': 0, 'accessibility': 1, 'description': 'MAIA(BARCA)'},
+        {'line_code': '4M', 'direction_code': 0, 'accessibility': 2, 'description': 'MAIA (CÂMARA)'},
+        {'line_code': '11M', 'direction_code': 1, 'accessibility': 2, 'description': 'HOSP. S. JOÃO'}
+    ]
+}
+```
+---
+
+## _get_stop_real_times(stop_code)_
+```PYTHON
+from stcp.api import get_stop_real_times
+next_buses = get_stop_real_times('TRD1')
+```
+
+### Result
+```JSON
+[
+    {'line_code': '304', 'time': '20:30'}, 
+    {'line_code': '200', 'time': '20:33'}, 
+    {'line_code': '600', 'time': '20:44'}, 
+    {'line_code': '304', 'time': '20:50'}
+]
+```
+
+# Utility examples
+
+## _get_all_stops()_
+```PYTHON
+from stcp.util import get_all_stops
+all_stops = get_all_stops()
+```
+
+### Result
+```JSON
+{'VDN1', 'SAL3', 'FLU6', 'CHA1', 'VIS1', 'CRVH2', 'JD1', 'JBR1', 'LCMS1', ...}
+```
+---
+
+## _stop_departures(stop_code)_
+```PYTHON
+from stcp.util import stop_departures
+next_departures = stop_departures('TRD1')
+```
+
+### Result
+```JSON
+{
+    '200': ['20:33'],
+    '304': ['20:30', '20:50'],
+    '600': ['20:44']
+}
+```
+---
+
+## _follow_line(stop_code)_
+```PYTHON
+from stcp.util import follow_line
+next_departures = follow_line('903', '1')
+```
+
+### Result
+```JSON
+[
+    ('VILAR DO PARAÍSO', '21:22'), 
+    ('JUNTA FREG. VILAR DO PARAÍSO', '21:23'), 
+    ('ALVES REDOL', '21:24'), 
+    ('QTA DAS ROSAS', '21:25'), 
+    ('FERREIRA DE CASTRO', '21:25'),
+    ('LABORIM', '21:26'), 
+    ('ALAMEDA CEDRO', '21:27'),
+    ...
+]
+```
diff --git a/main.py b/main.py
@@ -1,13 +1,16 @@
 from stcp.api import get_stop_real_times, get_lines, get_line_directions, get_stop_data, get_line_stops
-from stcp.util import follow_line, stop_departures
+from stcp.util import follow_line, stop_departures, get_all_stops
 
-# usage examples
+# API examples
 all_lines = get_lines()
 line_directions = get_line_directions('903')
 line_stops = get_line_stops('903', '0')
 stop_data = get_stop_data('TRD1')
 next_buses = get_stop_real_times('TRD1')
 
+
+# utility examples
+# all_stops = get_all_stops()
 next_departures = stop_departures('TRD1')
 
 times = follow_line('903', '1')

diff --git a/setup.py b/setup.py
@@ -5,7 +5,7 @@
 
 setup(
     name='stcp_api',
-    version='1.1.0',
+    version='1.1.1',
     author='Guilherme Borges',
     author_email='[email protected]',
     description='Unofficial API to retrieve STCP information for public transit buses in Porto, Portugal',