merge changes

.gitignore

@@ -0,0 +1 @@
+*.mpy

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "files.exclude": {
+        "**/*.mpy": true
+    }
+}

CHANGELOG.md

@@ -1,5 +1,5 @@
 # History
 
-## 0.1.0 (2021-03-20)
+## 0.1.0 (2021-05-22)
 
 * First release

LICENSE

@@ -16,17 +16,3 @@ GNU GENERAL PUBLIC LICENSE
 
     You should have received a copy of the GNU General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-Also add information on how to contact you by electronic and paper mail.
-
-  You should also get your employer (if you work as a programmer) or school,
-if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU GPL, see
-<http://www.gnu.org/licenses/>.
-
-  The GNU General Public License does not permit incorporating your program
-into proprietary programs.  If your program is a subroutine library, you
-may consider it more useful to permit linking proprietary applications with
-the library.  If this is what you want to do, use the GNU Lesser General
-Public License instead of this License.  But first, please read
-<http://www.gnu.org/philosophy/why-not-lgpl.html>.

README.md

@@ -1,38 +1,45 @@
 # Uberserk - Lichess boards API client for MicroPython
 
-Uberserk is a light version of berserk ported for MicroPython with enough functionality
+Uberserk is a light version of berserk ported to MicroPython with enough functionality
 to support play on custom chess boards.
 
-This project is [rhgrant10/berserk](https://github.com/rhgrant10/berserk/tree/master/berserk) with modifications that allow it to run on MicroPython. Developed and tested using ESP32.
+This project is [rhgrant10/berserk](https://github.com/rhgrant10/berserk/) with modifications that allow it to run on MicroPython. Developed and tested using ESP32.
 
-Some changes to MicroPython packages were needed as well so uberserk comes with its own datetime.py and (my)urequests.py.
+Some changes to MicroPython packages were needed as well so uberserk comes with its own datetime.py and urequests.py.
 
 ### MCU requirements
 Uberserk requires a decently sized RAM, ESP32-WROOM do not cut it and ESP32-WROVER with SPI RAM are required.
 
+
 ### Changes to datetime.py
 - line 1360:   `t, frac = divmod(t, 1)`
     -  1.0 -> 1 to prevent TypeError: can't convert float to int on line 1372
-- line 1371:
-```try:  # fix per https://github.com/smlng/pycayennelpp/issues/53
-            y, m, d, hh, mm, ss, weekday, jday, dst = converter(t)
-        except ValueError:
-            y, m, d, hh, mm, ss, weekday, jday = converter(t)
+- line 1371 replace with try block as per https://github.com/smlng/pycayennelpp/issues/53
+```
+try:
+    y, m, d, hh, mm, ss, weekday, jday, dst = converter(t)
+except ValueError:
+    y, m, d, hh, mm, ss, weekday, jday = converter(t)
 ```
 
-Check datetime compatibility. No errors must be seen:
+- line 917 add `__new__` to tzinfo as per https://github.com/micropython/micropython-lib/pull/338:
+```
+    def __new__(cls, *args, **kwargs):
+        return object.__new__(cls)
+```
+
+
+Check datetime compatibility (reference for developers; the lib must be moved out of uberserk namespace first or imports below changed). No errors must be seen:
 ```
 >>> ts=1612971162
->>> from datetime import datetime
->>> from datetime import timezone
+>>> from datetime import datetime, timezone
 >>> datetime.fromtimestamp(ts, timezone.utc)
 ```
 
 ### Changes to urequests.py
-- line 29: add `self.raw.setblocking(False)`
-    - REST APIs work without it but streaming APIs would block
+- implement iterator protocol for Response
 
-### Changes to Berserk to port to MicroPython
+### Changes to Berserk to port it to MicroPython
 - replace all formatted strings with .format() or %-based string formatting
 - remove dependency on json.JSONDecoder, ndjson
 - remove dependency on requests.Session
@@ -48,43 +55,42 @@ Check datetime compatibility. No errors must be seen:
   - only get_ongoing()
 - Users
 - Teams
+- Challenges
 
 #### The following functionality of berserk is dropped:
 - most of Account
 - most of Games
 - Bots
-- Challenges
 - Tournaments
 - Broadcasts
 - Simuls
 - Studies
 
-### Installation
+## Installation
 
 Assuming you have MicroPython installed on your MCU and have it connected via a serial line over USB with device name /dev/tty.usbserial-0001:
 
 First get to MicroPython REPL to create a directory for uberserk:
 ```
 screen /dev/tty.usbserial-0001 115200
 >>> import uos
+>>> uos.mkdir('lib')
 >>> uos.mkdir('lib/uberserk')
->>> ^a d
 ```
 Then exit back to shell, free the serial device (killall screen, replace as needed) and copy over the files:
 ```
 killall screen
-git clone ...
+git clone https://github.com/mkomon/uberserk.git
 cd uberserk
-rshell -p /dev/tty.usbserial-0001 cp datetime.py myrequests.py /pyboard/lib
 rshell -p /dev/tty.usbserial-0001 cp uberserk/*.py /pyboard/lib/uberserk
 ```
 
-### Usage
+## Usage
 ```
 >>> import uberserk
 >>> 
->>> OAUTH_TOKEN = 'get-one-online'
->>> client = uberserk.Client(OAUTH_TOKEN)
+>>> AUTH_TOKEN = 'get-one-online'
+>>> client = uberserk.Client(AUTH_TOKEN)
 >>> account_info = client.account.get()
 
 >>> account_info.keys()
@@ -96,9 +102,24 @@ dict_keys(['nbFollowers', 'completionRate', 'perfs', 'url', 'followable', 'langu
     ...
 ```
 
+### Differences from Berserk
+Uberserk behaves like Berserk, API responses are handled and formatted just like in Berserk. It may feel slower because it cannot use connection pooling for different requests and each API call opens a HTTPS connection. Streaming API is where uberserk differs notably: while generators that read from streaming APIs in Berserk are blocking in uberserk they do not block. This avoids the need to use threads and allows the generators be called from the main loop or any other loop.
 
-### Credits
+#### Streaming API usage
+```
+for event in client.board.stream_game_state(game_id)
+    if not event:
+        # no new events for now
+        utime.sleep_ms(500)
+        continue
+    # process event
+    ...
+```
 
-- [rhgrant10/berserk](https://github.com/rhgrant10/berserk/tree/master/berserk) for the original Berserk client
+After the condition (no new events) you can wait and `continue` to simulate blocking behavior of the generator, like in Berserk, or you can `break` and do other things before some event arrives and you run the loop again to check.
 
+### Credits
 
+- [Robert Grant](https://github.com/rhgrant10) for the original Berserk client [rhgrant10/berserk](https://github.com/rhgrant10/berserk/tree/master/berserk)
+- CPython Developers for [datetime](https://github.com/micropython/micropython-lib/blob/master/datetime/datetime.py) package of [micropython-lib](https://github.com/micropython/micropython-lib/)
+- Paul Sokolovsky for [urequests](https://github.com/micropython/micropython-lib/blob/master/urequests/urequests.py) package of [micropython-lib](https://github.com/micropython/micropython-lib/)

uberserk/LICENSE-MIT.txt

@@ -0,0 +1,23 @@
+=============== MIT License ===============
+
+The MIT License (MIT)
+
+Copyright (c) 2013, 2014 micropython-lib contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.