More code cleanup and readme

README.md

@@ -27,3 +27,16 @@ This creates two users, `mouse@your-domain.com` with password `password123` and
 And go to the app at localhost:8000
 
 For most testing, you'll want to use ngrok. Remember to set the DOMAIN in settings.py to your ngrok domain.
+
+
+## Structure
+
+All the url routing is in `fedireads/urls.py`. This includes the application views (your home page, user page, book page, etc),
+application endpoints (things that happen when you click buttons), and federation api endpoints (inboxes, outboxes, webfinger, etc).
+
+The application views and actions are in `fedireads/views.py`. The internal actions call api handlers which deal with federating content.
+Outgoing messages (any action done by a user that is federated out), as well as outboxes, live in `fedireads/outgoing.py`, and all handlers for incoming
+messages, as well as inboxes and webfinger, live in `fedireads/incoming.py`. Misc api functions live in `fedireads/api.py`, which is
+probably not a good name for that file.
+
+Connection to openlibrary.org to get book data is handled in `fedireads/openlibrary.py`.

fedireads/openlibrary.py

@@ -1,39 +1,56 @@
 ''' activitystream api and books '''
 from django.core.exceptions import ObjectDoesNotExist
+import requests
+
 from fedireads.models import Author, Book, Work
 from fedireads.settings import OL_URL
-import requests
+
 
 def get_or_create_book(olkey, user=None, update=True):
     ''' add a book '''
-    # check if this is a valid open library key, and a book
+    # TODO: check if this is a valid open library key, and a book
     olkey = olkey
-    response = requests.get(OL_URL + olkey + '.json')
-    if not response.ok:
-        response.raise_for_status()
 
     # get the existing entry from our db, if it exists
     try:
         book = Book.objects.get(openlibrary_key=olkey)
         if not update:
             return book
+        # we have the book, but still want to update it from OL
     except ObjectDoesNotExist:
+        # no book was found, so we start creating a new one
         book = Book(openlibrary_key=olkey)
+
+    # load the book json from openlibrary.org
+    response = requests.get(OL_URL + olkey + '.json')
+    if not response.ok:
+        response.raise_for_status()
+
     data = response.json()
     book.data = data
+
     if user and user.is_authenticated:
         book.added_by = user
+
+    # great, we can update our book.
     book.save()
+
+    # we also need to know the author and works related to this book.
     for work_id in data['works']:
         work_id = work_id['key']
         book.works.add(get_or_create_work(work_id))
+
     for author_id in data['authors']:
         author_id = author_id['key']
         book.authors.add(get_or_create_author(author_id))
+
     return book
 
+
 def get_or_create_work(olkey):
     ''' load em up '''
+    # TODO: validate that this is a work key
+    # TODO: error handling
     try:
         work = Work.objects.get(openlibrary_key=olkey)
     except ObjectDoesNotExist:
@@ -43,8 +60,11 @@ def get_or_create_work(olkey):
         work.save()
     return work
 
+
 def get_or_create_author(olkey):
     ''' load that author '''
+    # TODO: validate that this is an author key
+    # TODO: error handling
     try:
         author = Author.objects.get(openlibrary_key=olkey)
     except ObjectDoesNotExist:

fedireads/views.py

@@ -48,6 +48,7 @@ def home(request):
 def user_login(request):
     ''' authentication '''
     # send user to the login page
+    # TODO: login with localname or email
     if request.method == 'GET':
         return TemplateResponse(request, 'login.html')