clear-skies 2.0.0__py3-none-any.whl → 2.0.1__py3-none-any.whl

{clear_skies-2.0.0.dist-info → clear_skies-2.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: clear-skies
-Version: 2.0.0
+Version: 2.0.1
 Summary: A framework for building backends in the cloud
 License: MIT
 Author: Conor Mancone
@@ -25,7 +25,7 @@ Requires-Dist: pymysql (>=1.1.0,<2.0.0) ; extra == "mysql"
 Requires-Dist: requests (>=2.31.0,<3.0.0)
 Requires-Dist: typing-extensions (>=4.12.0,<5.0.0) ; python_version == "3.10"
 Requires-Dist: wrapt (>=1.16.0,<2.0.0)
-Project-URL: Repository, https://github.com/cmancone/clearskies
+Project-URL: Repository, https://github.com/clearskies-py/clearskies
 Description-Content-Type: text/markdown
 
 # clearskies

{clear_skies-2.0.0.dist-info → clear_skies-2.0.1.dist-info}/RECORD

@@ -1,12 +1,12 @@
 clearskies/__init__.py,sha256=HLBu0CXipIp-Cr_-iBfpN4UlrFwsjTNFOwF9i0iN5i0,1241
 clearskies/action.py,sha256=x_T05XaC0m-BYPZWaSR94XbE7T5ZK1vRtSfEszfZuDg,121
 clearskies/authentication/__init__.py,sha256=MxXNCWhKbha7TPu_MAyssfTdOCEDSNBwzshEHx8gfHo,525
-clearskies/authentication/authentication.py,sha256=rMzX5pveW00RXrAujLGqxOhCMLnvOlAxdQTwl-kCEQk,1203
-clearskies/authentication/authorization.py,sha256=SMbEhX-kwvV5ivFToEVcGR7xqm95DkRg4RAPVLLStOc,534
+clearskies/authentication/authentication.py,sha256=N-g2qNDGuJaSlMwc_SRwsjAuqOMLI2nKfUzSCF7HOFo,1240
+clearskies/authentication/authorization.py,sha256=3XEOUlQx9XeRPpNEk4GCa-xWafrz-3Xd0T1PCSFuVxY,570
 clearskies/authentication/authorization_pass_through.py,sha256=d3XKcUWmI_u9QBBTGKrU1hdD-LM56iH60Qv_xc8TE6k,512
-clearskies/authentication/jwks.py,sha256=LPDYjZVVK8aoDUERSyE5pjoac8nA9_TaQtiZRLIZLcs,4826
+clearskies/authentication/jwks.py,sha256=5QVqfXsT95jEKkbm1xnUZsEoIwqMLviDyDRlK_s8xAw,4888
 clearskies/authentication/public.py,sha256=GSNl4X4fnB25BZoXSo8nqL0iZCa9rzfvPfIsJ2Y34B4,84
-clearskies/authentication/secret_bearer.py,sha256=DP3M5rMW48CToD_ITlrYpaHGyOanyBVGMQQmLo6BK6Y,17608
+clearskies/authentication/secret_bearer.py,sha256=3eENEx38lTbiLkHKixE_m32RVeKt_ZTwjCc2WGMft7I,17618
 clearskies/autodoc/__init__.py,sha256=JRUAmd0he8iGlgiZvxewLMIXJqnOFEdvlaKAtHpC2lo,124
 clearskies/autodoc/formats/__init__.py,sha256=3rhoLKmEwT6PljaHvOl9qdeMIXyD7PQBZbqZKy5Mb5I,56
 clearskies/autodoc/formats/oai3_json/__init__.py,sha256=C9DzR38Uu0t41osMzhQx6K-hyaNWA1t6agTzOXW9k88,142
@@ -48,11 +48,11 @@ clearskies/autodoc/schema/schema.py,sha256=KZ4r88OUMzbeV4DQ3yUhK8bHS_zJiimsWPWc1
 clearskies/autodoc/schema/string.py,sha256=GXRI-aU8PYmjfnhmfaOe4vq7JASb-aB4SiFeG-EmJY0,60
 clearskies/backends/__init__.py,sha256=krBB3gHLP-lVYkm5ksdK7teEtouAHhL3EC__WGVnF4A,3157
 clearskies/backends/api_backend.py,sha256=fRt0U5pZn41ltZUKjbYguJrtNxchSJICLOYIV1bJV7A,54901
-clearskies/backends/backend.py,sha256=1IgX4ts9x8qxoVS2csdDflimVQx0leeVNhvgeUaFn40,5050
+clearskies/backends/backend.py,sha256=_TFMXAHgIY-vPGhx8SYjSTbVd9r-6KpLbLnfNsCXuV8,5874
 clearskies/backends/cursor_backend.py,sha256=lMnkHATU2Fxr0ihgrVnvI9IVnUPxNfjzpkdJIok2mXY,14360
 clearskies/backends/memory_backend.py,sha256=fXgbFcTvbZeKHs4CsI_yNsofHSjWqZqY9QWI7uJzVws,34260
 clearskies/backends/secrets_backend.py,sha256=zlS2ELM6pgS18tt6KvyOPqHWMMFCqsu76prEnZ8GeE0,4323
-clearskies/column.py,sha256=PKpHsGihsMP4Ph1xzbCvvgjpt5NuiNpGZUGLKvXlNVM,52091
+clearskies/column.py,sha256=4FdsU4hh1u7ekY42uh2_A5J13RtPxaf84NRj39gbTak,51963
 clearskies/columns/__init__.py,sha256=a__-1hv-aMV3RU0Sd-BEkfItSJaG51EF2VeRQoTdka8,1990
 clearskies/columns/audit.py,sha256=vwWQR_lNKonihb71qUoKQwzLQ5VA1ASFOm7ggA9jJ3Y,7628
 clearskies/columns/belongs_to_id.py,sha256=H6yWsnMgr1za8hRWW40R499SVuTd11Ixb1YCacqCTHM,17820
@@ -89,7 +89,7 @@ clearskies/columns/timestamp.py,sha256=_1T20qTVHeLEqqKlxb7IFwUvcYsLWPrGMylPwvVCG
 clearskies/columns/updated.py,sha256=_gJw8W_HlNKr-bHTE4eHqMqbFqJ4JcSzTRDLOt7d0Us,3481
 clearskies/columns/uuid.py,sha256=WjWqkGHU6MlxjNQYW8lscgsOfG4mDQnJZGxEqQAoeQU,2432
 clearskies/configs/README.md,sha256=4-r2FvkrBTrKkcKgJ5O3Qj1RZ7nnkknenKze4XYlQDs,4827
-clearskies/configs/__init__.py,sha256=xoll5EalODwI_W1HtWutAIJ_ndzLyWLqvfZonVUtmYY,5017
+clearskies/configs/__init__.py,sha256=XnnokLN7tYOXRhupmHEIVH-InTHlPJZ28kNHPhzOuLM,5093
 clearskies/configs/actions.py,sha256=5OwrokU8uTSSQ_6SvL94SOP5JVkvRRFGAXNcCdMt8aQ,1388
 clearskies/configs/any.py,sha256=_nac0cZY9uRhwGQZqj2N72ZFehYqOedb97lPADP3Yg8,352
 clearskies/configs/any_dict.py,sha256=B8Gd0zwC-6UxvMvPsXMJySzVMADxG3oxnrhgBnJWCGo,871
@@ -101,10 +101,11 @@ clearskies/configs/boolean_or_callable.py,sha256=nvvWD_A5HoxW-6_rZJL23_1517T8IQ6
 clearskies/configs/callable_config.py,sha256=gcTlRwCppdaj1gFuCugc4ahxMCTEDKD_z_f85eadWpc,650
 clearskies/configs/columns.py,sha256=WhdpPUiwVqwBO2XCDDiMym2nWr_1-L1JoICyob4T6Wo,1258
 clearskies/configs/conditions.py,sha256=a09bVac4-10ZtKPQGSu_e9VnHnwITwy_7_T4NekXpgs,1008
-clearskies/configs/config.py,sha256=YD7uDn1bbW4TYlcFjKFvx90HoSGbIYn77qjdAHm6z9E,833
+clearskies/configs/config.py,sha256=Mw9wnPzEekHGfmNFH9f2vJ3BOPx3l1ktxwZc95flyQg,873
 clearskies/configs/datetime.py,sha256=jRYXwLeTUqh8FNwWq_0yYoSH8YU9NEhYhuQScr56nTg,653
 clearskies/configs/datetime_or_callable.py,sha256=81YCDk0g5cIxdXxgem1Ei6m7gUI213Cfryp3GyBfpD4,799
 clearskies/configs/endpoint.py,sha256=NEDthtdPzejAot7yzUjC01PvQJR9BIyk5YnWXCi1w9I,759
+clearskies/configs/endpoint_list.py,sha256=I_o5T46XT-I-tbQODJbpCF9LkgEccOz97mYFZuwjx4M,1144
 clearskies/configs/float.py,sha256=3870-DkoXCyeOSwUGa69BzhG4XI_tNfei5cX-q1b1UQ,585
 clearskies/configs/float_or_callable.py,sha256=lIOg20Xw0AOB0k3I7f0b98srVgMWQKcyM4aWRT0tUI4,708
 clearskies/configs/integer.py,sha256=d6uoQaUoE01rrWOsxYl1vHG_raUFmB0AUOgoCWwOVC0,584
@@ -137,14 +138,14 @@ clearskies/configs/writeable_model_column.py,sha256=ZwroRcvmNznggtNMSZiAmKAvllcV
 clearskies/configs/writeable_model_columns.py,sha256=D8E4aQRg1MX8-TM8lkyrWE-G_YoX2eerX4KLszgk0hA,323
 clearskies/configurable.py,sha256=FFkKwlQk17KOLnZiTsTF3hrCu2WxRSuuddNNhz9aySY,3049
 clearskies/contexts/__init__.py,sha256=f7XVUq2UKlDH6fjmcUWk6lbe9p_OaGpZ5ZjM6CuwTGQ,247
-clearskies/contexts/cli.py,sha256=1y7g45FiHbI3Q6JEmwskWVuXPWgmddyK49FfgSafR5U,227
-clearskies/contexts/context.py,sha256=ESnzmhZ7pjDVsmbT7eZTsR26ZvgV-aeeUGsDsT1oK0s,3109
-clearskies/contexts/wsgi.py,sha256=xXHb3m8m44dHKsPX4WLIFExWg5Do2Zv6mQtyb4V4pnM,547
-clearskies/contexts/wsgi_ref.py,sha256=awy-J4DELrVyD5E9FysPE5A_W9JLEZOf2g1hIAogJUA,1733
+clearskies/contexts/cli.py,sha256=HSzHieVsD3a0uQb6FBue17HVT4PjSY8LWhjW3rw7lQw,285
+clearskies/contexts/context.py,sha256=jbd8JdDkFruHiAYHZWrLjOvqz31LkvfApArCOVwkyfo,3630
+clearskies/contexts/wsgi.py,sha256=lENadrI53LYUCa3Mn4JjxhTn-53Ry9l6w2kBU3CQ5AM,611
+clearskies/contexts/wsgi_ref.py,sha256=Tkq0QYE7_ZdYvEcRKbyh-6UwwuExUadKdylwdxcCmQQ,1814
 clearskies/di/__init__.py,sha256=uJ1NkACEIaot7ALr3M6vQ55Pe9By_s_1z52ssAnw28E,466
 clearskies/di/additional_config.py,sha256=65INxw8aqTZQsyaKPj-aQmd6FBe4_4DwibXGgWYBy14,5139
 clearskies/di/additional_config_auto_import.py,sha256=XYw0Kcnp6hp-ee-c0YjiATwJvRb2E82xk9PuoX9dGRY,758
-clearskies/di/di.py,sha256=g6v2Pjga1EUJ6BaHlX8HL3qoK1z6l_iPl7oNN6eJD9Y,45131
+clearskies/di/di.py,sha256=pWNzUDd2nxnKZP12I5SpAL3PYBWCmnM6jsT7i7cEGCM,45137
 clearskies/di/inject/__init__.py,sha256=plEkWId-VyhvqX5KM2HhdCqi7_ZJzPmFz69cPAo812Y,643
 clearskies/di/inject/by_class.py,sha256=dUA_ZseLZWT30wnkg272rWwe5FzUpr0gCMMQP_HFahc,796
 clearskies/di/inject/by_name.py,sha256=oEfzeotUXPbUAiBrkE7i19nD2ISk59EEwCH3pcgSmqA,639
@@ -162,11 +163,11 @@ clearskies/di/test_module/__init__.py,sha256=7YHQF7JHP0FdI7GdEGANSZ_t1EISQYhUNm1
 clearskies/di/test_module/another_module/__init__.py,sha256=8SRmHPDepLKGWTUSc1ucDF6U8mJPsNDsBDmBQCpzPWo,35
 clearskies/di/test_module/module_class.py,sha256=I_-wnMuHfbsvti-7d2Z4bXnr6deo__uvww9nds9qrlE,46
 clearskies/end.py,sha256=Z4C9n7OvBky_640oJ8d19jIr_ap1iqjGJqqO6s_zF5g,8919
-clearskies/endpoint.py,sha256=4Wzl89zmNwhKDGqMMlQhzy5MJWx5x_hkbYMDdNguFzw,48817
-clearskies/endpoint_group.py,sha256=ZAkkUsOyd5GFyh_kWFezuO7f8dOzS49pH9bcaaDuW7A,10997
+clearskies/endpoint.py,sha256=ewxvcbRRJ-R1u0c39NU4yEVFDr4hvdkwgcdKD7O4m4g,48855
+clearskies/endpoint_group.py,sha256=K1HLIMhU75ezC_SytwA-4j3ViFjjGZOBurRN5Urc6lk,11299
 clearskies/endpoints/__init__.py,sha256=CZJQ3rHF1GA0QvH9CKxUFM1pEnJrg-2wAj5rzIDdzjc,689
 clearskies/endpoints/advanced_search.py,sha256=c1fj81nohHGqe56t00o6kLN3XIh3kfy-aKy_C1pxwgw,21835
-clearskies/endpoints/callable.py,sha256=fdVAa2Dhfg3-OikoE9-PiDnJuZRD0MarQKcdRGwlnaA,13904
+clearskies/endpoints/callable.py,sha256=mg1kWafU8owq_PiGHO3rr9Wl-kSRcBlnsWLb-Wd67xc,13957
 clearskies/endpoints/create.py,sha256=Fgm8ZN2WreGTjWreSyty1c80SP8_qHcjK_be9hpWELw,8757
 clearskies/endpoints/delete.py,sha256=GWnD5-By_5clJzDi8Mac5aeL7HArDpRet3Qo7GPinWk,5296
 clearskies/endpoints/get.py,sha256=w-NWyq9GcQqyBHGS-dTqRdaXRXdvooD-iZ_doDbemNA,10382
@@ -198,13 +199,13 @@ clearskies/input_outputs/input_output.py,sha256=W5h8a9XFEqwi3h6v17okblz8sOozUj-m
 clearskies/input_outputs/programmatic.py,sha256=gfsNFIfiF5cvxi1aS9SgArcKYUgkL5gyxjCMQLwgivY,1711
 clearskies/input_outputs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clearskies/input_outputs/wsgi.py,sha256=94tgWxiwpwvJA9G4nG-hCHteg0pq9pIDCVhnheZuAQc,2544
-clearskies/model.py,sha256=qdGco45F2icRLxhNy5Chtuww-q72jac6eoUpvFn40bU,26492
+clearskies/model.py,sha256=Pt1DDU5K9okrygJ7_dsRlYf4bRosrtiAVOffk536-Rg,47259
 clearskies/parameters_to_properties.py,sha256=kbU9Ln2mU3XX4p-QNepGgS4HiQ1BUuJnhx9T6kgB9jw,1004
 clearskies/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clearskies/query/__init__.py,sha256=ISF80_cG3rd574sRTdKKPxAdlSjtQh_ClXKKs_MSSSo,277
 clearskies/query/condition.py,sha256=9RJrYya1Kfzx0L_BMDKQhYkN9dB7NAq5kRK5mz51YdY,8624
 clearskies/query/join.py,sha256=4lrDUQzck7klKY_VYkc4SVK95SVwyy3SVTvasnsAEyc,4713
-clearskies/query/query.py,sha256=J_fJ8XZXvZxZ0nZd276WXaxzOFb-bVZ-PTaAqddGhOk,6076
+clearskies/query/query.py,sha256=t9tV67CeI6I1u5Uhu6KPT_qiFjvLc3GnwVM2acbXuAU,6088
 clearskies/query/sort.py,sha256=c-EtIkjg3kLjwSTdXD7sfyx-mNUhAepUV-2izprh3iY,754
 clearskies/schema.py,sha256=9S0RuFBiydsDy4kATy2BBsXJ9aWHILW0ja_q9F4kxb0,2872
 clearskies/secrets/__init__.py,sha256=WauemayzKCr-guvMu6wCL4hQUIbkDJFuNKEm8Rd6cUs,136
@@ -215,7 +216,7 @@ clearskies/secrets/akeyless.py,sha256=IUI4RYD-XdNQvyhpuElnw_O74ZY4tJUUtCHmd0dArU
 clearskies/secrets/exceptions/__init__.py,sha256=j-SLHD-DL0CT4cZXibD9kXHk63JEl_UKX6xL_nq1EfE,32
 clearskies/secrets/exceptions/not_found.py,sha256=_lZwovDrd18dUHDop5pF4mhexBPNr126xF2gOLA2-EA,36
 clearskies/secrets/secrets.py,sha256=TYN0T7XjmvETtSacDKEkyGGO9kDFCoPl5A7FNkvyNj4,1593
-clearskies/security_header.py,sha256=__gPaE6F_MQKpt1cFh_ZOky7I44K3yiy0Z9FeEYscK0,202
+clearskies/security_header.py,sha256=suV3PMGFFJzMIsfDiT4t1sArkLVGzepyoftY0ddBWkM,431
 clearskies/security_headers/__init__.py,sha256=JUpc4Y8dNBinDQAkP7OOABR7N787-lRR23boSWmY6Us,285
 clearskies/security_headers/cache_control.py,sha256=1gxASHq74Azpm_19kDFEyT55KuO7gYeyauuvTAZVeaA,2279
 clearskies/security_headers/cors.py,sha256=8cErvdprnT3IlBaoENbNz43UwFpaUWI_NXtJJaYEH3c,1859
@@ -225,7 +226,7 @@ clearskies/security_headers/x_content_type_options.py,sha256=47DEQpj8HBSa-_TImW-
 clearskies/security_headers/x_frame_options.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clearskies/test_base.py,sha256=Nw6qwsPMOx-QT_6wXn6f9P4BcA7OeGrs83IC2naNMYY,205
 clearskies/typing.py,sha256=Kme9es5c_lw4qQCbCL7lKXtDemVl0_qBy7jxKIu4yyg,378
-clearskies/validator.py,sha256=u9xNOfXbDOTpP1XLu-5O_QGJ6Ja674HRCW6QCxtlD1c,723
+clearskies/validator.py,sha256=nGFwe74LMJnEO7r2mgwd_V25bLpxUDH7IMolm-zk-3w,1332
 clearskies/validators/__init__.py,sha256=Hz0L5Y7EkeK4Px6WcdQ3ku6VqUGpLHX0ZWwCpT1ts1U,1248
 clearskies/validators/after_column.py,sha256=WPbto20CEYaKjjQtO-0t1s5DvTKW7ipDMNYaqNlr1zY,2394
 clearskies/validators/before_column.py,sha256=fDXhgPwGvnjk1Xy6iwebE8q--BeD48uu3cVGpRGTSBc,528
@@ -242,7 +243,7 @@ clearskies/validators/minimum_value.py,sha256=Vz0e_9U5KYqBGqfrVBOtPiVtmNPWwFEGPA
 clearskies/validators/required.py,sha256=gNKEZsYP04PQZc0bE_EpgFw4dWrcKnml2D2QthuD7lY,1410
 clearskies/validators/timedelta.py,sha256=TLtFs4KhOmJpDdrf9mmsSiLtt8yz-i0ym30Cw4EcykY,1960
 clearskies/validators/unique.py,sha256=m59azxUecp7t3WFCehcmQ6E1ZpyXdcLQ1KOSm_p5Hn4,1077
-clear_skies-2.0.0.dist-info/LICENSE,sha256=3Ehd0g3YOpCj8sqj0Xjq5qbOtjjgk9qzhhD9YjRQgOA,1053
-clear_skies-2.0.0.dist-info/METADATA,sha256=JLZ7NxtWMmVIm5nNmlP1XYzqAagPw-g11XmJpJ_Ndgo,1757
-clear_skies-2.0.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-clear_skies-2.0.0.dist-info/RECORD,,
+clear_skies-2.0.1.dist-info/LICENSE,sha256=3Ehd0g3YOpCj8sqj0Xjq5qbOtjjgk9qzhhD9YjRQgOA,1053
+clear_skies-2.0.1.dist-info/METADATA,sha256=vihY3StAUiiXlBvo2d81PEbB0po4THFpN_FFz6sewPw,1762
+clear_skies-2.0.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+clear_skies-2.0.1.dist-info/RECORD,,

clearskies/authentication/authentication.py

@@ -12,6 +12,10 @@ if TYPE_CHECKING:
 
 
 class Authentication(clearskies.configurable.Configurable, requests.auth.AuthBase):
+    """
+    Authentication!
+    """
+
     is_public = True
     can_authorize = False
     has_dynamic_credentials = False

clearskies/authentication/authorization.py

@@ -1,4 +1,8 @@
 class Authorization:
+    """
+    Authorization!
+    """
+
     def gate(self, authorization_data, input_output):
         """
         Return True/False to denote if the given user, as represented by the authorization data, should be allowed access.

clearskies/authentication/jwks.py

@@ -10,8 +10,13 @@ from clearskies.security_headers.cors import Cors
 
 
 class Jwks(Authentication, clearskies.di.InjectableProperties):
-    """The URL where the JWKS can be found."""
+    """
+    Validate a JWT against a JWKS (JSON Web Key Set)
+    """
 
+    """
+    The URL of the JWKS
+    """
     jwks_url = clearskies.configs.String(required=True)
 
     """

clearskies/authentication/secret_bearer.py

@@ -495,7 +495,7 @@ class SecretBearer(Authentication, clearskies.di.InjectableProperties):
         if not self._alternate_secret:
             self._alternate_secret = (
                 self.secrets.get(self.alternate_secret_key)
-                if self.secret_key
+                if self.alternate_secret_key
                 else self.environment.get(self.alternate_environment_key)
             )
         return self._alternate_secret

clearskies/backends/backend.py

@@ -9,6 +9,19 @@ from clearskies.autodoc.schema import Schema as AutoDocSchema
 
 
 class Backend(ABC):
+    """
+    Conecting models to their data since 2020!
+
+    The backend system acts as a flexible layer between models and their data sources.  By changing the backend attached to a model,
+    you change where the model fetches and saves data.  This might be a database, an in-memory data store, a dynamodb table,
+    an API, and more.  This allows you to interact with a variety of data sources with the models acting as a standardized API.
+    Since endpoints also rely on the models for their functionality, this means that you can easily build API endpoints and
+    more for a variety of data sources with a minimal amount of code.
+
+    Of course, not all data sources support all functionality present in the model.  Therefore, you do still need to have
+    a fair understanding of how your data sources work.
+    """
+
     supports_n_plus_one = False
     can_count = True
 

clearskies/column.py

@@ -24,13 +24,10 @@ if TYPE_CHECKING:
 
 class Column(clearskies.configurable.Configurable, clearskies.di.InjectableProperties):
     """
-    The base column.
+    Columns are used to build schemes and enable a variety of levels of automation with clearskies.
 
-    This class (well, the children that extend it) are used to define the columns that exist in a given model class -
-    they help you build your schema.  The column definitions are then used by handlers and other aspects of the
-    clearskies framework to automate things like input validation, front-end/backend-transformations, and more.
-    Many column classes have their own configuration settings, but there are also some common configuration settings
-    defined here.
+    Columns are used to define your schemas in clearskies, especially via models.  The column definitions are then used by endpoints
+    and other aspects of the clearskies framework to automate things like input validation, front-end/backend-transformations, and more.
     """
 
     """

clearskies/configs/__init__.py

@@ -80,6 +80,7 @@ from .config import Config
 from .datetime import Datetime
 from .datetime_or_callable import DatetimeOrCallable
 from .endpoint import Endpoint
+from .endpoint_list import EndpointList
 from .float import Float
 from .float_or_callable import FloatOrCallable
 from .integer import Integer
@@ -126,6 +127,8 @@ __all__ = [
     "Config",
     "Datetime",
     "DatetimeOrCallable",
+    "Endpoint",
+    "EndpointList",
     "Float",
     "FloatOrCallable",
     "Joins",

clearskies/configs/config.py

@@ -1,5 +1,8 @@
+from typing import Any
+
+
 class Config:
-    def __init__(self, required=False, default=None):
+    def __init__(self, required: bool = False, default: Any = None):
         self.required = required
         self.default = default
 

clearskies/configs/endpoint_list.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clearskies.configs import config
+
+if TYPE_CHECKING:
+    from clearskies.endpoint import Endpoint as EndpointBase
+
+
+class EndpointList(config.Config):
+    def __set__(self, instance, value: list[EndpointBase]):
+        if not isinstance(value, list):
+            raise TypeError(
+                f"{error_prefix} attempt to set a value of type '{value.__class__.__name__}' to a parameter that requries a list of endpoints."
+            )
+        for index, item in enumerate(value):
+            if not hasattr(item, "top_level_authentication_and_authorization"):
+                error_prefix = self._error_prefix(instance)
+                raise TypeError(
+                    f"{error_prefix} attempt to set a value of type '{item.__class__.__name__}' for item #{index+1} when all items in the list should be instances of clearskies.End."
+                )
+        instance._set_config(self, value)
+
+    def __get__(self, instance, parent) -> list[EndpointBase]:
+        if not instance:
+            return self  # type: ignore
+        return instance._get_config(self)

clearskies/contexts/cli.py

@@ -3,5 +3,9 @@ from clearskies.input_outputs import Cli as CliInputOutput
 
 
 class Cli(Context):
+    """
+    Run an application via a CLI command
+    """
+
     def __call__(self):  # type: ignore
         return self.execute_application(CliInputOutput())

clearskies/contexts/context.py

@@ -15,8 +15,21 @@ if TYPE_CHECKING:
 
 
 class Context:
+    """
+    Context: a flexible way to connect applications to hosting strategies.
+    """
+
     di: Di = None  # type: ignore
 
+    """
+    The application to execute.
+
+    This can be a callable, an endpoint, or an endpoint group.  If passed a callable, the callable can request any
+    standard or defined dependencies and should return the desired response.  It can also raise any exception from
+    clearskies.exceptions.
+    """
+    application: Callable | clearskies.endpoint.Endpoint | clearskies.endpoint_group.EndpointGroup = None  # type: ignore
+
     def __init__(
         self,
         application: Callable | clearskies.endpoint.Endpoint | clearskies.endpoint_group.EndpointGroup,

clearskies/contexts/wsgi.py

@@ -12,5 +12,9 @@ from clearskies.input_outputs import Wsgi as WsgiInputOutput
 
 
 class Wsgi(Context):
+    """
+    Connect your application to a WSGI server.
+    """
+
     def __call__(self, env, start_response):  # type: ignore
         return self.execute_application(WsgiInputOutput(env, start_response))

clearskies/contexts/wsgi_ref.py

@@ -12,6 +12,10 @@ from clearskies.input_outputs import Wsgi as WsgiInputOutput
 
 
 class WsgiRef(Context):
+    """
+    Use a built in WSGI server (for development purposes only).
+    """
+
     port: int = 8080
 
     def __init__(

clearskies/di/di.py

@@ -23,7 +23,7 @@ class Di:
     Build a dependency injection object.
 
     The dependency injection (DI) container is a key part of clearskies, so understanding how to both configure
-    them and get dependencies for your classes is important.  Note however that there you don't often have
+    them and get dependencies for your classes is important.  Note however that you don't often have
     to interact with the dependency injection container directly.  All of the configuration options for
     the DI container are also available to all the contexts, which is typically how you will build clearskies
     applications.  So, while you can create a DI container and use it directly, typically you'll just follow
@@ -648,7 +648,7 @@ class Di:
         its name and type-hint.
         """
         built_value = self.build_class_from_type_hint(argument_name, type_hint, context=context, cache=True)
-        if built_value:
+        if built_value is not None:
             return built_value
         return self.build_from_name(argument_name, context=context, cache=True)
 

clearskies/endpoint.py

@@ -32,15 +32,16 @@ class Endpoint(
     clearskies.di.InjectableProperties,
 ):
     """
-    Endpoints - the clearskies workhorse.
+    Automating drudgery!
 
     With clearskies, endpoints exist to offload some drudgery and make your life easier, but they can also
     get out of your way when you don't need them.  Think of them as pre-built endpoints that can execute
     common functionality needed for web applications/APIs.  Instead of defining a function that fetches
     records from your backend and returns them to the end user, you can let the list endpoint do this for you
     with a minimal amount of configuration.  Instead of making an endpoint that creates records, just deploy
-    a create endpoint.  Each endpoint has their own configuration settings, but there are some configuration
-    settings that are common to all endpoints, which are listed below:
+    a create endpoint.  While this gives clearskies some helpful capabiltiies for automation, it also has
+    the Callable endpoint which simply calls a developer-defined function, and therefore allows clearskies to
+    act like a much more typical framework.
     """
 
     """
@@ -342,7 +343,7 @@ class Endpoint(
     """
     The model class used by this endpoint.
 
-    The majority of endpoints require a model class that tells the endpoint where to get/save its data.
+    The endpoint will use this to fetch/save/validate incoming data as needed.
     """
     model_class = clearskies.configs.ModelClass(default=None)
 

clearskies/endpoint_group.py

@@ -217,11 +217,24 @@ class EndpointGroup(
     The dependency injection container
     """
     di = clearskies.di.inject.Di()
+
+    """
+    The base URL for the endpoint group.
+
+    This URL is added as a prefix to all endpoints attached to the group.  This includes any named URL parameters:
+    """
     url = clearskies.configs.String(default="")
+
+    """
+    The list of endpoints connected to this endpoint group
+    """
+    endpoints = clearskies.configs.EndpointList()
+
     response_headers = clearskies.configs.StringListOrCallable(default=[])
     authentication = clearskies.configs.Authentication(default=Public())
     authorization = clearskies.configs.Authorization(default=Authorization())
     security_headers = clearskies.configs.SecurityHeaders(default=[])
+
     cors_header: SecurityHeader = None  # type: ignore
     has_cors: bool = False
     endpoints_initialized = False

clearskies/endpoints/callable.py

@@ -23,13 +23,13 @@ class Callable(Endpoint):
     """
     An endpoint that executes a user-defined function.
 
-    The Callable endpoint does exactly that - you provide a function that will be called when the endpoin is invoked.  Like
-    all callables invoked by clearskies, you can request any defined depenndency that can be provided by the clearskies
+    The Callable endpoint does exactly that - you provide a function that will be called when the endpoint is invoked.  Like
+    all callables invoked by clearskies, you can request any defined dependency that can be provided by the clearskies
     framework.
 
     Whatever you return will be returned to the client.  By default, the return value is sent along in the `data` parameter
     of the standard clearskies response.  To suppress this behavior, set `return_standard_response` to `False`.  You can also
-    return an model instance, a model query, or a list of model instances and the callable endpoint will automatically return
+    return a model instance, a model query, or a list of model instances and the callable endpoint will automatically return
     the columns specified in `readable_column_names` to the client.
 
     Here's a basic working example:
@@ -300,6 +300,7 @@ class Callable(Endpoint):
                     converted_models,
                     number_results=len(response) if response.backend.can_count else None,
                     next_page=response.next_page_data(),
+                    limit=response.get_query().limit,
                 )
 
         # or did they return a list of models?

clearskies/model.py

@@ -19,13 +19,166 @@ class Model(Schema, InjectableProperties):
     """
     A clearskies model.
 
-    To be useable, a model class needs three things:
+    To be useable, a model class needs four things:
 
-     1. Column definitions
-     2. The name of the id column
-     3. A backend
-     4. A destination name (equivalent to a table name for SQL backends)
+     1. The name of the id column
+     2. A backend
+     3. A destination name (equivalent to a table name for SQL backends)
+     4. Columns
 
+    In more detail:
+
+    ### Id Column Name
+
+    clearskies assumes that all models have a column that uniquely identifies each record.  This id column is
+    provided where appropriate in the lifecycle of the model save process to help connect and find related records.
+    It's defined as a simple class attribute called `id_column_name`.  There **MUST** be a column with the same name
+    in the column definitions.  A simple approach to take is to use the Uuid column as an id column.  This will
+    automatically provide a random UUID when the record is first created.  If you are using auto-incrementing integers,
+    you can simply use an `Int` column type and define the column as auto-incrementing in your database.
+
+    ### Backend
+
+    Every model needs a backend, which is an object that extends clearskies.Backend and is attached to the
+    `backend` attribute of the model class.  clearskies comes with a variety of backends in the `clearskies.backends`
+    module that you can use, and you can also define your own or import more from additional packages.
+
+    ### Destination Name
+
+    The destination name is the equivalent of a table name in other frameworks, but the name is more generic to
+    reflect the fact that clearskies is intended to work with a variety of backends - not just SQL databases.
+    The exact meaning of the destination name depends on the backend: for a cursor backend it is in fact used
+    as the table name when fetching/storing records.  For the API backend it is frequently appended to a base
+    URL to reach the corect endpoint.
+
+    This is provided by a class function call `destination_name`.  The base model class declares a generic method
+    for this which takes the class name, converts it from title case to snake case, and makes it plural.  Hence,
+    a model class called `User` will have a default destination name of `users` and a model class of `OrderProduct`
+    will have a default destination name of `order_products`.  Of course, this system isn't pefect: your backend
+    may have a different convention or you may have one of the many words in the english language that are
+    exceptions to the grammatical rules of making words plural.  In this case you can simply extend the method
+    and change it according to your needs, e.g.:
+
+    ```
+    from typing import Self
+    import clearskies
+
+    class Fish(clearskies.Model):
+        @classmethod
+        def destination_name(cls: type[Self]) -> str:
+            return "fish"
+    ```
+
+    ### Columns
+
+    Finally, columns are defined by attaching attributes to your model class that extend clearskies.Column.  A variety
+    are provided by default in the clearskies.columns module, and you can always create more or import them from
+    other packages.
+
+    ### Fetching From the Di Container
+
+    In order to use a model in your application you need to retrieve it from the dependency injection system.  Like
+    everything, you can do this by either the name or with type hinting.  Models do have a special rule for
+    injection-via-name: like all classes their dependency injection name is made by converting the class name from
+    title case to snake case, but they are also available via the pluralized name.  Here's a quick example of all
+    three approaches for dependency injection:
+
+    ```
+    import clearskies
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+
+    def my_application(user, users, by_type_hint: User):
+        return {
+            "all_are_user_models": isinstance(user, User) and isinstance(users, User) and isinstance(by_type_hint, User)
+        }
+
+    cli = clearskies.contexts.Cli(my_application, classes=[User])
+    cli()
+    ```
+
+    Note that the `User` model class was provided in the `classes` list sent to the context: that's important as it
+    informs the dependency injection system that this is a class we want to provide.  It's common (but not required)
+    to put all models for a clearskies application in their own separate python module and then provide those to
+    the depedency injection system via the `modules` argument to the context.  So you may have a directory structure
+    like this:
+
+    ```
+    ├── app/
+    │   └── models/
+    │       ├── __init__.py
+    │       ├── category.py
+    │       ├── order.py
+    │       ├── product.py
+    │       ├── status.py
+    │       └── user.py
+    └── api.py
+    ```
+
+    Where `__init__.py` imports all the models:
+
+    ```
+    from app.models.category import Category
+    from app.models.order import Order
+    from app.models.proudct import Product
+    from app.models.status import Status
+    from app.models.user import User
+
+    __all__ = ["Category", "Order", "Product", "Status", "User"]
+    ```
+
+    Then in your main application you can just import the whole `models` module into your context:
+
+    ```
+    import app.models
+
+    cli = clearskies.contexts.cli(SomeApplication, modules=[app.models])
+    ```
+
+    ### Adding Dependencies
+
+    The base model class extends `clearskies.di.InjectableProperties` which means that you can inject dependencies into your model
+    using the `di.inject` classes.  Here's an example that demonstrates dependency injection for models:
+
+    ```
+    import datetime
+    import clearskies
+
+    class SomeClass:
+        # Since this will be built by the DI system directly, we can declare dependencies in the __init__
+        def __init__(self, some_date):
+            self.some_date = some_date
+
+    class User(clearskies.Model):
+        id_column_name = "id"
+        backend = clearskies.backends.MemoryBackend()
+
+        utcnow = clearskies.di.inject.Utcnow()
+        some_class = clearskies.di.inject.ByClass(SomeClass)
+
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String()
+
+        def some_date_in_the_past(self):
+            return self.some_class.some_date < self.utcnow
+
+    def my_application(user):
+        return user.some_date_in_the_past()
+
+    cli = clearskies.contexts.Cli(
+        my_application,
+        classes=[User],
+        bindings={
+            "some_date": datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=1),
+        }
+    )
+    cli()
+    ```
     """
 
     _previous_data: dict[str, Any] = {}
@@ -240,10 +393,12 @@ class Model(Schema, InjectableProperties):
         return not columns[key].values_match(old_value, new_value)
 
     def previous_value(self: Self, key: str):
+        """Return the value of a column from before the most recent save."""
         self.no_queries()
         return getattr(self.__class__, key).transform(self._previous_data.get(key))
 
     def delete(self: Self, except_if_not_exists=True) -> bool:
+        """Delete a record."""
         self.no_queries()
         if not self:
             if except_if_not_exists:
@@ -454,30 +609,154 @@ class Model(Schema, InjectableProperties):
 
     def where(self: Self, where: str | Condition) -> Self:
         """
-        Add the given condition to the query.
+        Add a condition to a query.
+
+        The `where` method (in combination with the `find` method) is typically the starting point for query records in
+        a model.  You don't *have* to add a condition to a model in order to fetch records, but of course it's a very
+        common use case.  Conditions in clearskies can be built from the columns or can be constructed as SQL-like
+        string conditions, e.g. `model.where("name=Bob")` or `model.where(model.name.equals("Bob"))`.  The latter
+        provides strict type-checking, while the former does not.  Either way they have the same result.  The list of
+        supported operators for a given column can be seen by checking the `_allowed_search_operators` attribute of the
+        column class.  Most columns accept all allowed operators, which are:
+
+         - "<=>"
+         - "!="
+         - "<="
+         - ">="
+         - ">"
+         - "<"
+         - "="
+         - "in"
+         - "is not null"
+         - "is null"
+         - "like"
+
+        When working with string conditions, it is safe to inject user input into the condition.  The allowed
+        format for conditions is very simple: `f"{column_name}\\s?{operator}\\s?{value}"`.  This makes it possible to
+        unambiguously separate all three pieces from eachother.  It's not possible to inject malicious payloads into either
+        the column names or operators because both are checked against a strict allow list (e.g. the columns declared in the
+        model or the list of allowed operators above).  The value is then extracted from the leftovers, and this is
+        provided to the backend separately so it can use it appropriately (e.g. using prepared statements for the cursor
+        backend).  Of course, you generally shouldn't have to inject user input into conditions very often because, most
+        often, the various list/search endpoints do this for you, but if you have to do it there are no security
+        concerns.
+
+        You can include a table name before the column name, with the two separated by a period.  As always, if you do this,
+        ensure that you include a supporting join statement (via the `join` method - see it for examples).
+
+        When you call the `where` method it returns a new model object with it's query configured to include the additional
+        condition.  The original model object remains unchanged.  Multiple conditions are always joined with AND.  There is
+        no explicit option for OR.  The closest is using an IN condition.
+
+        To access the results you have to iterate over the resulting model.  If you are only expecting one result
+        and want to work directly with it, then you can use `model.find(condition)` or `model.where(condition).first()`.
+
+        Example:
+        ```python
+        import clearskies
 
-        This method returns a new object with the updated query.  The original model object is unmodified.
+        class Order(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
 
-        Conditions should be an SQL-like string of the form [column][operator][value] with an optional table prefix.
-        You can safely inject user input into the value.  The column name will also be checked against the searchable
-        columns for the model class, and an exception will be thrown if the column doesn't exist or is not searchable.
+            id = clearskies.columns.Uuid()
+            user_id = clearskies.columns.String()
+            status = clearskies.columns.Select(["Pending", "In Progress"])
+            total = clearskies.columns.Float()
 
-        Multiple conditions are always joined with AND.  There is no explicit option for OR.  The closest is using an
-        IN condition.
+        def my_application(orders):
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 25})
+            orders.create({"user_id": "Alice", "status": "In Progress", "total": 15})
+            orders.create({"user_id": "Jane", "status": "Pending", "total": 30})
 
-        Examples:
-        ```python
-        for record in (
-            models.where("order_id=5").where("status IN ('ACTIVE','PENDING')").where("other_table.id=asdf")
-        ):
-            print(record.id)
+            return [order.user_id for order in orders.where("status=Pending").where(Order.total.greater_than(25))]
+
+        cli = clearskies.contexts.Cli(
+            my_application,
+            classes=[Order],
+        )
+        cli()
         ```
+
+        Which, if ran, returns: `["Jane"]`
+
         """
         self.no_single_model()
         return self.with_query(self.get_query().add_where(where if isinstance(where, Condition) else Condition(where)))
 
     def join(self: Self, join: str) -> Self:
-        """Add a join clause to the query."""
+        """
+        Add a join clause to the query.
+
+        As with the `where` method, this expects a string which is parsed accordingly.  The syntax is not as flexible as
+        SQL and expects a format of:
+
+        ```
+        [left|right|inner]? join [right_table_name] ON [right_table_name].[right_column_name]=[left_table_name].[left_column_name].
+        ```
+
+        This is case insensitive.  Aliases are allowed.  If you don't specify a join type it defaults to inner.
+        Here are two examples of valid join statements:
+
+         - `join orders on orders.user_id=users.id`
+         - `left join user_orders as orders on orders.id=users.id`
+
+        Note that joins are not strictly limited to SQL-like backends, but of course no all backends will support joining.
+
+        A basic example:
+
+        ```
+        import clearskies
+
+        class User(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+
+            id = clearskies.columns.Uuid()
+            name = clearskies.columns.String()
+
+        class Order(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+
+            id = clearskies.columns.Uuid()
+            user_id = clearskies.columns.BelongsToId(User, readable_parent_columns=["id", "name"])
+            user = clearskies.columns.BelongsToModel("user_id")
+            status = clearskies.columns.Select(["Pending", "In Progress"])
+            total = clearskies.columns.Float()
+
+        def my_application(users, orders):
+            jane = users.create({"name": "Jane"})
+            another_jane = users.create({"name": "Jane"})
+            bob = users.create({"name": "Bob"})
+
+            # Jane's orders
+            orders.create({"user_id": jane.id, "status": "Pending", "total": 25})
+            orders.create({"user_id": jane.id, "status": "Pending", "total": 30})
+            orders.create({"user_id": jane.id, "status": "In Progress", "total": 35})
+
+            # Another Jane's orders
+            orders.create({"user_id": another_jane.id, "status": "Pending", "total": 15})
+
+            # Bob's orders
+            orders.create({"user_id": bob.id, "status": "Pending", "total": 28})
+            orders.create({"user_id": bob.id, "status": "In Progress", "total": 35})
+
+            # return all orders for anyone named Jane that have a status of Pending
+            return orders.join("join users on users.id=orders.user_id").where("users.name=Jane").sort_by("total", "asc").where("status=Pending")
+
+        cli = clearskies.contexts.Cli(
+            clearskies.endpoints.Callable(
+                my_application,
+                model_class=Order,
+                readable_column_names=["user", "total"],
+            ),
+            classes=[Order, User],
+        )
+        cli()
+
+        ```
+        """
         self.no_single_model()
         return self.with_query(self.get_query().add_join(Join(join)))
 
@@ -498,6 +777,7 @@ class Model(Schema, InjectableProperties):
         return False
 
     def group_by(self: Self, group_by_column_name: str) -> Self:
+        """Add a group by clause to the query."""
         self.no_single_model()
         return self.with_query(self.get_query().set_group_by(group_by_column_name))
 
@@ -510,6 +790,41 @@ class Model(Schema, InjectableProperties):
         secondary_direction: str = "",
         secondary_table_name: str = "",
     ) -> Self:
+        """
+        Add a sort by clause to the query.  You can sort by up to two columns at once.
+
+        Example:
+        ```
+        import clearskies
+
+        class Order(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+
+            id = clearskies.columns.Uuid()
+            user_id = clearskies.columns.String()
+            status = clearskies.columns.Select(["Pending", "In Progress"])
+            total = clearskies.columns.Float()
+
+        def my_application(orders):
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 25})
+            orders.create({"user_id": "Alice", "status": "In Progress", "total": 15})
+            orders.create({"user_id": "Alice", "status": "Pending", "total": 30})
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 26})
+
+            return orders.sort_by("user_id", "asc", secondary_column_name="total", secondary_direction="desc")
+
+        cli = clearskies.contexts.Cli(
+            clearskies.endpoints.Callable(
+                my_application,
+                model_class=Order,
+                readable_column_names=["user_id", "total"],
+            ),
+            classes=[Order],
+        )
+        cli()
+        ```
+        """
         self.no_single_model()
         sort = Sort(primary_table_name, primary_column_name, primary_direction)
         secondary_sort = None
@@ -518,10 +833,96 @@ class Model(Schema, InjectableProperties):
         return self.with_query(self.get_query().set_sort(sort, secondary_sort))
 
     def limit(self: Self, limit: int) -> Self:
+        """
+        Set the number of records to return.
+
+        ```
+        import clearskies
+
+        class Order(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+
+            id = clearskies.columns.Uuid()
+            user_id = clearskies.columns.String()
+            status = clearskies.columns.Select(["Pending", "In Progress"])
+            total = clearskies.columns.Float()
+
+        def my_application(orders):
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 25})
+            orders.create({"user_id": "Alice", "status": "In Progress", "total": 15})
+            orders.create({"user_id": "Alice", "status": "Pending", "total": 30})
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 26})
+
+            return orders.limit(2)
+
+        cli = clearskies.contexts.Cli(
+            clearskies.endpoints.Callable(
+                my_application,
+                model_class=Order,
+                readable_column_names=["user_id", "total"],
+            ),
+            classes=[Order],
+        )
+        cli()
+        ```
+        """
         self.no_single_model()
         return self.with_query(self.get_query().set_limit(limit))
 
     def pagination(self: Self, **pagination_data) -> Self:
+        """
+        Set the pagination parameter(s) for the query.
+
+        The exact details of how pagination work depend on the backend.  For instance, the cursor and memory backend
+        expect to be given a `start` parameter, while an API backend will vary with the API, and the dynamodb backend
+        expects a kwarg called `cursor`.  As a result, it's necessary to check the backend documentation to understand
+        how to properly set pagination.  The endpoints automatically account for this because backends are required
+        to declare pagination details via the `allowed_pagination_keys` method.  If you attempt to set invalid
+        pagination data via this method, clearskies will raise a ValueError.
+
+        Example:
+        ```
+        import clearskies
+
+        class Order(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+
+            id = clearskies.columns.Uuid()
+            user_id = clearskies.columns.String()
+            status = clearskies.columns.Select(["Pending", "In Progress"])
+            total = clearskies.columns.Float()
+
+        def my_application(orders):
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 25})
+            orders.create({"user_id": "Alice", "status": "In Progress", "total": 15})
+            orders.create({"user_id": "Alice", "status": "Pending", "total": 30})
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 26})
+
+            return orders.sort_by("total", "asc").pagination(start=2)
+
+        cli = clearskies.contexts.Cli(
+            clearskies.endpoints.Callable(
+                my_application,
+                model_class=Order,
+                readable_column_names=["user_id", "total"],
+            ),
+            classes=[Order],
+        )
+        cli()
+        ```
+
+        However, if the return line in `my_application` is switched for either of these:
+
+        ```
+        return orders.sort_by("total", "asc").pagination(start="asdf")
+        return orders.sort_by("total", "asc").pagination(something_else=5)
+        ```
+
+        Will result in an exception that explains exactly what is wrong.
+
+        """
         self.no_single_model()
         error = self.backend.validate_pagination_data(pagination_data, str)
         if error:
@@ -538,8 +939,36 @@ class Model(Schema, InjectableProperties):
         This is just shorthand for `models.where("column=value").find()`.  Example:
 
         ```python
-        model = models.find("column=value")
-        print(model.id)
+        import clearskies
+
+        class Order(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+
+            id = clearskies.columns.Uuid()
+            user_id = clearskies.columns.String()
+            status = clearskies.columns.Select(["Pending", "In Progress"])
+            total = clearskies.columns.Float()
+
+        def my_application(orders):
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 25})
+            orders.create({"user_id": "Alice", "status": "In Progress", "total": 15})
+            orders.create({"user_id": "Jane", "status": "Pending", "total": 30})
+
+            jane = orders.find("user_id=Jane")
+            jane.total = 35
+            jane.save()
+
+            return {
+                "user_id": jane.user_id,
+                "total": jane.total,
+            }
+
+        cli = clearskies.contexts.Cli(
+            my_application,
+            classes=[Order],
+        )
+        cli()
         ```
         """
         self.no_single_model()
@@ -564,13 +993,48 @@ class Model(Schema, InjectableProperties):
         """
         Loop through all available pages of results and returns a list of all models that match the query.
 
-        NOTE: this loads up all records in memory before returning (e.g. it isn't using generators yet), so
-        expect delays for large record sets.
+        If you don't set a limit on a query, some backends will return all records but some backends have a
+        default maximum number of results that they will return.  In the latter case, you can use `paginate_all`
+        to fetch all records by instructing clearskies to iterate over all pages.  This is possible because backends
+        are required to define how pagination works in a way that clearskies can automatically understand and
+        use.  To demonstrate this, the following example sets a limit of 1 which stops the memory backend
+        from returning everything, and then uses `paginate_all` to fetch all records.  The memory backend
+        doesn't have a default limit, so in practice the `paginate_all` is unnecessary here, but this is done
+        for demonstration purposes.
 
-        ```python
-        for model in models.where("column=value").paginate_all():
-            print(model.id)
         ```
+        import clearskies
+
+        class Order(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+
+            id = clearskies.columns.Uuid()
+            user_id = clearskies.columns.String()
+            status = clearskies.columns.Select(["Pending", "In Progress"])
+            total = clearskies.columns.Float()
+
+        def my_application(orders):
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 25})
+            orders.create({"user_id": "Alice", "status": "In Progress", "total": 15})
+            orders.create({"user_id": "Alice", "status": "Pending", "total": 30})
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 26})
+
+            return orders.limit(1).paginate_all()
+
+        cli = clearskies.contexts.Cli(
+            clearskies.endpoints.Callable(
+                my_application,
+                model_class=Order,
+                readable_column_names=["user_id", "total"],
+            ),
+            classes=[Order],
+        )
+        cli()
+        ```
+
+        NOTE: this loads up all records in memory before returning (e.g. it isn't using generators yet), so
+        expect delays for large record sets.
         """
         self.no_single_model()
         next_models = self.with_query(self.get_query())
@@ -611,11 +1075,43 @@ class Model(Schema, InjectableProperties):
 
     def first(self: Self) -> Self:
         """
-        Return the first model matching the given query.
+        Return the first model for a given query.
+
+        The `where` method returns an object meant to be iterated over.  If you are expecting your query to return a single
+        record, then you can use first to turn that directly into the matching model so you don't have to iterate over it:
+
+        ```
+        import clearskies
+
+        class Order(clearskies.Model):
+            id_column_name = "id"
+            backend = clearskies.backends.MemoryBackend()
+
+            id = clearskies.columns.Uuid()
+            user_id = clearskies.columns.String()
+            status = clearskies.columns.Select(["Pending", "In Progress"])
+            total = clearskies.columns.Float()
+
+        def my_application(orders):
+            orders.create({"user_id": "Bob", "status": "Pending", "total": 25})
+            orders.create({"user_id": "Alice", "status": "In Progress", "total": 15})
+            orders.create({"user_id": "Jane", "status": "Pending", "total": 30})
+
+            jane = orders.where("status=Pending").where(Order.total.greater_than(25)).first()
+            jane.total = 35
+            jane.save()
+
+            return {
+                "user_id": jane.user_id,
+                "total": jane.total,
+            }
+
+        cli = clearskies.contexts.Cli(
+            my_application,
+            classes=[Order],
+        )
+        cli()
 
-        ```python
-        model = models.where("column=value").sort_by("age", "DESC").first()
-        print(model.id)
         ```
         """
         self.no_single_model()

clearskies/query/query.py

@@ -99,13 +99,13 @@ class Query:
         """Return the properties of this query as a dictionary so it can be used as kwargs when creating another one."""
         return {
             "model_class": self.model_class,
-            "conditions": self.conditions,
-            "joins": self.joins,
-            "sorts": self.sorts,
+            "conditions": [*self.conditions],
+            "joins": [*self.joins],
+            "sorts": [*self.sorts],
             "limit": self.limit,
             "group_by": self.group_by,
             "pagination": self.pagination,
-            "selects": self.selects,
+            "selects": [*self.selects],
             "select_all": self.select_all,
         }
 

clearskies/security_header.py

@@ -2,6 +2,13 @@ from clearskies.configurable import Configurable
 
 
 class SecurityHeader(Configurable):
+    """
+    Attach all the various security headers to endpoints.
+
+    The security header classes can be attached directly to both endpoints and endpoint groups and
+    are used to set all the various security headers.
+    """
+
     is_cors = False
 
     def set_headers_for_input_output(self, input_output):

clearskies/validator.py

@@ -11,6 +11,18 @@ if TYPE_CHECKING:
 
 
 class Validator(ABC, configurable.Configurable):
+    """
+    Attach input validation rules to columns!
+
+    The validators provide a way to attach input validation logic to columns.  The columns themselves already
+    provide basic validation (making sure strings are strings, integers are integers, etc...) but these classes
+    allow for more detailed rules.
+
+    It's important to understand that validators only apply to client input, which means that input validation
+    is only enforced by appropriate endpoints.  If you inject a model into a function of your own and execute
+    a save operation with it, validators will **NOT** be checked.
+    """
+
     is_unique = False
     is_required = False