Skip to content

Commit 5351105

Browse files
authored
Merge pull request #86 from Neradoc/fix-documentation-params-and-code-blocks
Fix documentation of params and code blocks
2 parents 0caa25b + a31b699 commit 5351105

File tree

2 files changed

+53
-21
lines changed

2 files changed

+53
-21
lines changed

adafruit_io/adafruit_io.py

+52-19
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,7 @@ def _on_disconnect_mqtt(self, client, userdata, return_code):
146146
def _on_message_mqtt(self, client, topic, payload):
147147
"""Runs when the client calls on_message. Parses and returns
148148
incoming data from Adafruit IO feeds.
149+
149150
:param MQTT client: A MQTT Client Instance.
150151
:param str topic: MQTT topic response from Adafruit IO.
151152
:param str payload: MQTT payload data response from Adafruit IO.
@@ -201,9 +202,9 @@ def add_feed_callback(self, feed_key, callback_method):
201202
202203
NOTE: The callback_method registered to this method
203204
will only execute during loop().
205+
204206
:param str feed_key: Adafruit IO feed key.
205207
:param str callback_method: Name of callback method.
206-
207208
"""
208209
validate_feed_key(feed_key)
209210
self._client.add_topic_callback(
@@ -216,20 +217,21 @@ def remove_feed_callback(self, feed_key):
216217
217218
After this method is called, incoming messages
218219
call the shared on_message.
219-
:param str feed_key: Adafruit IO feed key.
220220
221+
:param str feed_key: Adafruit IO feed key.
221222
"""
222223
validate_feed_key(feed_key)
223224
self._client.remove_topic_callback("{0}/f/{1}".format(self._user, feed_key))
224225

225226
def loop(self, timeout=1):
226227
"""Manually process messages from Adafruit IO.
227228
Call this method to check incoming subscription messages.
229+
228230
:param int timeout: Socket timeout, in seconds.
229231
230232
Example usage of polling the message queue using loop.
231233
232-
..code-block:: python
234+
.. code-block:: python
233235
234236
while True:
235237
io.loop()
@@ -240,6 +242,7 @@ def loop(self, timeout=1):
240242
def subscribe(self, feed_key=None, group_key=None, shared_user=None):
241243
"""Subscribes to your Adafruit IO feed or group.
242244
Can also subscribe to someone else's feed.
245+
243246
:param str feed_key: Adafruit IO Feed key.
244247
:param str group_key: Adafruit IO Group key.
245248
:param str shared_user: Owner of the Adafruit IO feed, required for shared feeds.
@@ -283,6 +286,7 @@ def subscribe_to_errors(self):
283286

284287
def subscribe_to_randomizer(self, randomizer_id):
285288
"""Subscribes to a random data stream created by the Adafruit IO Words service.
289+
286290
:param int randomizer_id: Random word record you want data for.
287291
"""
288292
self._client.subscribe(
@@ -292,6 +296,7 @@ def subscribe_to_randomizer(self, randomizer_id):
292296
def subscribe_to_weather(self, weather_record, forecast):
293297
"""Subscribes to a weather forecast using the Adafruit IO PLUS weather
294298
service. This feature is only avaliable to Adafruit IO PLUS subscribers.
299+
295300
:param int weather_record: Weather record you want data for.
296301
:param str forecast: Forecast data you'd like to recieve.
297302
"""
@@ -303,7 +308,9 @@ def subscribe_to_weather(self, weather_record, forecast):
303308

304309
def subscribe_to_time(self, time_type):
305310
"""Adafruit IO provides some built-in MQTT topics for getting the current server time.
311+
306312
:param str time_type: Current Adafruit IO server time. Can be 'seconds', 'millis', or 'iso'.
313+
307314
Information about these topics can be found on the Adafruit IO MQTT API Docs.:
308315
https://io.adafruit.com/api/docs/mqtt.html#time-topics
309316
"""
@@ -315,6 +322,7 @@ def subscribe_to_time(self, time_type):
315322
def unsubscribe(self, feed_key=None, group_key=None, shared_user=None):
316323
"""Unsubscribes from an Adafruit IO feed or group.
317324
Can also subscribe to someone else's feed.
325+
318326
:param str feed_key: Adafruit IO Feed key.
319327
:param str group_key: Adafruit IO Group key.
320328
:param str shared_user: Owner of the Adafruit IO feed, required for shared feeds.
@@ -337,7 +345,6 @@ def unsubscribe(self, feed_key=None, group_key=None, shared_user=None):
337345
.. code-block:: python
338346
339347
client.unsubscribe('temperature', shared_user='adabot')
340-
341348
"""
342349
if shared_user is not None and feed_key is not None:
343350
validate_feed_key(feed_key)
@@ -361,10 +368,10 @@ def publish_multiple(self, feeds_and_data, timeout=3, is_group=False):
361368
:param bool is_group: Set to True if you're publishing to a group.
362369
363370
Example of publishing multiple data points on different feeds to Adafruit IO:
364-
..code-block:: python
365371
366-
client.publish_multiple([('humidity', 24.5), ('temperature', 54)])
372+
.. code-block:: python
367373
374+
client.publish_multiple([('humidity', 24.5), ('temperature', 54)])
368375
"""
369376
if isinstance(feeds_and_data, list):
370377
feed_data = []
@@ -393,38 +400,43 @@ def publish(self, feed_key, data, metadata=None, shared_user=None, is_group=Fals
393400
:param bool is_group: Set True if publishing to an Adafruit IO Group.
394401
395402
Example of publishing an integer to Adafruit IO on feed 'temperature'.
396-
..code-block:: python
403+
404+
.. code-block:: python
397405
398406
client.publish('temperature', 30)
399407
400408
Example of publishing a floating point value to feed 'temperature'.
401-
..code-block:: python
409+
410+
.. code-block:: python
402411
403412
client.publish('temperature', 3.14)
404413
405414
Example of publishing a string to feed 'temperature'.
406-
..code-block:: python
415+
416+
.. code-block:: python
407417
408418
client.publish('temperature, 'thirty degrees')
409419
410420
Example of publishing an integer to group 'weatherstation'.
411-
..code-block:: python
421+
422+
.. code-block:: python
412423
413424
client.publish('weatherstation', 12, is_group=True)
414425
415426
Example of publishing to a shared feed.
416-
..code-block:: python
427+
428+
.. code-block:: python
417429
418430
client.publish('temperature', shared_user='myfriend')
419431
420432
Example of publishing a value along with locational metadata to a feed.
421-
..code-block:: python
433+
434+
.. code-block:: python
422435
423436
data = 42
424437
# format: "lat, lon, ele"
425438
metadata = "40.726190, -74.005334, -6"
426439
io.publish("location-feed", data, metadata)
427-
428440
"""
429441
validate_feed_key(feed_key)
430442
if is_group:
@@ -445,10 +457,12 @@ def get(self, feed_key):
445457
"""Calling this method will make Adafruit IO publish the most recent
446458
value on feed_key.
447459
https://io.adafruit.com/api/docs/mqtt.html#retained-values
460+
448461
:param str feed_key: Adafruit IO Feed key.
449462
450463
Example of obtaining a recently published value on a feed:
451-
..code-block:: python
464+
465+
.. code-block:: python
452466
453467
io.get('temperature')
454468
"""
@@ -461,9 +475,9 @@ class IO_HTTP:
461475
Client for interacting with the Adafruit IO HTTP API.
462476
https://io.adafruit.com/api/docs/#adafruit-io-http-api
463477
464-
:param str adafruit_io_username: Adafruit IO Username
465-
:param str adafruit_io_key: Adafruit IO Key
466-
:param requests: A passed adafruit_requests module.
478+
:param str adafruit_io_username: Adafruit IO Username
479+
:param str adafruit_io_key: Adafruit IO Key
480+
:param requests: A passed adafruit_requests module.
467481
"""
468482

469483
def __init__(self, adafruit_io_username, adafruit_io_key, requests):
@@ -486,9 +500,9 @@ def _create_headers(io_headers):
486500
@staticmethod
487501
def _create_data(data, metadata):
488502
"""Returns a data payload as expected by the Adafruit IO HTTP API
503+
489504
:param data: Payload value.
490505
:param dict metadata: Payload metadata.
491-
492506
"""
493507
payload = {"value": data}
494508
if metadata: # metadata is expected as a dict, append key/vals
@@ -510,6 +524,7 @@ def _handle_error(response):
510524

511525
def _compose_path(self, path):
512526
"""Composes a valid API request path.
527+
513528
:param str path: Adafruit IO API URL path.
514529
"""
515530
return "https://io.adafruit.com/api/v2/{0}/{1}".format(self.username, path)
@@ -518,6 +533,7 @@ def _compose_path(self, path):
518533
def _post(self, path, payload):
519534
"""
520535
POST data to Adafruit IO
536+
521537
:param str path: Formatted Adafruit IO URL from _compose_path
522538
:param json payload: JSON data to send to Adafruit IO
523539
"""
@@ -532,6 +548,7 @@ def _post(self, path, payload):
532548
def _get(self, path):
533549
"""
534550
GET data from Adafruit IO
551+
535552
:param str path: Formatted Adafruit IO URL from _compose_path
536553
"""
537554
response = self._http.get(
@@ -545,6 +562,7 @@ def _get(self, path):
545562
def _delete(self, path):
546563
"""
547564
DELETE data from Adafruit IO.
565+
548566
:param str path: Formatted Adafruit IO URL from _compose_path
549567
"""
550568
response = self._http.delete(
@@ -559,6 +577,7 @@ def _delete(self, path):
559577
def send_data(self, feed_key, data, metadata=None, precision=None):
560578
"""
561579
Sends value data to a specified Adafruit IO feed.
580+
562581
:param str feed_key: Adafruit IO feed key
563582
:param str data: Data to send to the Adafruit IO feed
564583
:param dict metadata: Optional metadata associated with the data
@@ -579,6 +598,7 @@ def send_data(self, feed_key, data, metadata=None, precision=None):
579598
def send_batch_data(self, feed_key, data_list):
580599
"""
581600
Sends a batch array of data to a specified Adafruit IO feed
601+
582602
:param str feed_key: Adafruit IO feed key
583603
:param list Data: Data list to send
584604
"""
@@ -591,6 +611,7 @@ def receive_all_data(self, feed_key):
591611
"""
592612
Get all data values from a specified Adafruit IO feed. Data is
593613
returned in reverse order.
614+
594615
:param str feed_key: Adafruit IO feed key
595616
"""
596617
validate_feed_key(feed_key)
@@ -600,6 +621,7 @@ def receive_all_data(self, feed_key):
600621
def receive_data(self, feed_key):
601622
"""
602623
Return the most recent value for the specified feed.
624+
603625
:param string feed_key: Adafruit IO feed key
604626
"""
605627
validate_feed_key(feed_key)
@@ -609,6 +631,7 @@ def receive_data(self, feed_key):
609631
def delete_data(self, feed_key, data_id):
610632
"""
611633
Deletes an existing Data point from a feed.
634+
612635
:param string feed: Adafruit IO feed key
613636
:param string data_id: Data point to delete from the feed
614637
"""
@@ -620,6 +643,7 @@ def delete_data(self, feed_key, data_id):
620643
def create_new_group(self, group_key, group_description):
621644
"""
622645
Creates a new Adafruit IO Group.
646+
623647
:param str group_key: Adafruit IO Group Key
624648
:param str group_description: Brief summary about the group
625649
"""
@@ -630,6 +654,7 @@ def create_new_group(self, group_key, group_description):
630654
def delete_group(self, group_key):
631655
"""
632656
Deletes an existing group.
657+
633658
:param str group_key: Adafruit IO Group Key
634659
"""
635660
path = self._compose_path("groups/{0}".format(group_key))
@@ -638,16 +663,17 @@ def delete_group(self, group_key):
638663
def get_group(self, group_key):
639664
"""
640665
Returns Group based on Group Key
666+
641667
:param str group_key: Adafruit IO Group Key
642668
"""
643669
path = self._compose_path("groups/{0}".format(group_key))
644670
return self._get(path)
645671

646672
def create_feed_in_group(self, group_key, feed_name):
647673
"""Creates a new feed in an existing group.
674+
648675
:param str group_key: Group name.
649676
:param str feed_name: Name of new feed.
650-
651677
"""
652678
path = self._compose_path("groups/{0}/feeds".format(group_key))
653679
payload = {"feed": {"name": feed_name}}
@@ -656,6 +682,7 @@ def create_feed_in_group(self, group_key, feed_name):
656682
def add_feed_to_group(self, group_key, feed_key):
657683
"""
658684
Adds an existing feed to a group
685+
659686
:param str group_key: Group
660687
:param str feed_key: Feed to add to the group
661688
"""
@@ -668,6 +695,7 @@ def add_feed_to_group(self, group_key, feed_key):
668695
def get_feed(self, feed_key, detailed=False):
669696
"""
670697
Returns an Adafruit IO feed based on the feed key
698+
671699
:param str feed_key: Adafruit IO Feed Key
672700
:param bool detailed: Returns a more verbose feed record
673701
"""
@@ -681,6 +709,7 @@ def get_feed(self, feed_key, detailed=False):
681709
def create_new_feed(self, feed_key, feed_desc=None, feed_license=None):
682710
"""
683711
Creates a new Adafruit IO feed.
712+
684713
:param str feed_key: Adafruit IO Feed Key
685714
:param str feed_desc: Optional description of feed
686715
:param str feed_license: Optional feed license
@@ -695,6 +724,7 @@ def create_and_get_feed(
695724
):
696725
"""
697726
Attempts to return a feed; if the feed does not exist, it is created, and then returned.
727+
698728
:param str feed_key: Adafruit IO Feed Key
699729
:param bool detailed: Returns a more verbose existing feed record
700730
:param str feed_desc: Optional description of feed to be created
@@ -711,6 +741,7 @@ def create_and_get_feed(
711741
def delete_feed(self, feed_key):
712742
"""
713743
Deletes an existing feed.
744+
714745
:param str feed_key: Valid feed key
715746
"""
716747
validate_feed_key(feed_key)
@@ -722,6 +753,7 @@ def receive_weather(self, weather_id):
722753
"""
723754
Get data from the Adafruit IO Weather Forecast Service
724755
NOTE: This service is avaliable to Adafruit IO Plus subscribers only.
756+
725757
:param int weather_id: ID for retrieving a specified weather record.
726758
"""
727759
path = self._compose_path("integrations/weather/{0}".format(weather_id))
@@ -730,6 +762,7 @@ def receive_weather(self, weather_id):
730762
def receive_random_data(self, generator_id):
731763
"""
732764
Get data from the Adafruit IO Random Data Stream Service
765+
733766
:param int generator_id: Specified randomizer record
734767
"""
735768
path = self._compose_path("integrations/words/{0}".format(generator_id))

docs/api.rst

+1-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
API
2-
------------
1+
32
.. If you created a package, create one automodule per module in the package.
43
54
.. If your library file(s) are nested in a directory (e.g. /adafruit_foo/foo.py)

0 commit comments

Comments
 (0)