Improve validation, docs for token.expires_in

- accept 0 meaning no expiration, since folks have tried to use it that way
- clear error message for invalid (e.g. negative) values
- specify example in rest api doc so it doesn't default to invalid `0`
- better error if orm token fails to be retrieved

jupyterhub/orm.py

@@ -3,6 +3,7 @@
 # Distributed under the terms of the Modified BSD License.
 import enum
 import json
+import numbers
 from base64 import decodebytes, encodebytes
 from datetime import timedelta
 from functools import partial
@@ -813,7 +814,18 @@ class APIToken(Hashed, Base):
         else:
             assert service.id is not None
             orm_token.service = service
-        if expires_in is not None:
+        if expires_in:
+            if not isinstance(expires_in, numbers.Real):
+                raise TypeError(
+                    f"expires_in must be a positive integer or null, not {expires_in!r}"
+                )
+            expires_in = int(expires_in)
+            # tokens must always expire in the future
+            if expires_in < 1:
+                raise ValueError(
+                    f"expires_in must be a positive integer or null, not {expires_in!r}"
+                )
+
             orm_token.expires_at = cls.now() + timedelta(seconds=expires_in)
 
         db.commit()