#2 Implement Score API (done) [Implement main score API]

Author: omidraha

ReadMe.rst

@@ -1,19 +1,54 @@
+Intro
+=====
+
+This is a Github Score Application to rank repositories based on forks and starts.
+
+
+Stack
+=====
+
+In this application we used:
+
+* Python
+* FastAPI
+
+
+
 Install requirements
 ====================
 
-    $ pip install -r requirements.txt
+```bash
+
+$ pip install -r requirements.txt
+
+```
+
+Environments
+============
 
+```bash
+
+$ export GITHUB_ACCESS_TOKEN="YOUR_GITHUB_ACCESS_TOKEN"
+
+```
 
 Run server
 ==========
 
-    $ uvicorn main:app
+```bash
+
+$ uvicorn main:app
 
+```
 
 Run tests
 =========
 
-    $ pytest
+```bash
+
+$ pytest
+
+```
 
 Browse
 ======
@@ -23,9 +58,51 @@ Browse
     http://127.0.0.1:8000/score/
 
 
-Knowledge links
-===============
+Curl
+====
+
+```bash
+
+$ curl -X 'POST' 'http://127.0.0.1:8000/score/' -H 'accept: application/json' -H 'Content-Type: application/json' -d '{"repo":"python/cpython"}
+
+```
+
+TODO
+====
+
+    Cache external service API response for some short period of time for example for 1 hour in the Redis,
+    And maybe provide a new cache option for example `Cache-Control: no-cache` header to the `score` API
+
 
+Useful links
+============
 
-https://fastapi.tiangolo.com/tutorial/metadata/
 
+* https://fastapi.tiangolo.com/tutorial/metadata/
+* https://levelup.gitconnected.com/deploying-an-asynchronous-fastapi-on-nginx-unit-b038288bec5
+* https://dev.to/shuv1824/deploy-fastapi-application-on-ubuntu-with-nginx-gunicorn-and-uvicorn-3mbl
+* https://medium.com/analytics-vidhya/how-to-deploy-a-python-api-with-fastapi-with-nginx-and-docker-1328cbf41bc
+* https://stackoverflow.com/questions/67435296/how-to-access-fastapi-swaggerui-docs-behind-an-nginx-proxy
+* https://fastapi.tiangolo.com/advanced/behind-a-proxy/
+* https://www.reddit.com/r/flask/comments/j2289k/anyone_using_fastapi_in_production/
+* https://stackoverflow.com/questions/62976648/architecture-flask-vs-fastapi/62977786#62977786
+* https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker
+* https://fastapi.tiangolo.com/deployment/manually/
+* https://unit.nginx.orga
+* https://www.uvicorn.org/#running-with-gunicorn
+* https://github.com/encode/uvicorn
+* https://towardsdatascience.com/how-to-deploy-a-machine-learning-model-with-fastapi-docker-and-github-actions-13374cbd638a
+* https://fastapi.tiangolo.com/tutorial/first-steps/
+* https://unit.nginx.org/
+* https://fastapi.tiangolo.com/advanced/behind-a-proxy/
+* https://fastapi.tiangolo.com/deployment/manually/
+* https://www.uvicorn.org/#running-with-gunicorn
+* https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker
+* https://stackoverflow.com/a/63427961
+* https://stackoverflow.com/a/66426744
+* https://levelup.gitconnected.com/deploying-an-asynchronous-fastapi-on-nginx-unit-b038288bec5
+* https://dev.to/shuv1824/deploy-fastapi-application-on-ubuntu-with-nginx-gunicorn-and-uvicorn-3mbl
+* https://github.com/tiangolo/fastapi/issues/1034#issuecomment-591651300
+* https://fastapi.tiangolo.com/tutorial/body/
+* https://fastapi.tiangolo.com/tutorial/handling-errors/
+* https://gist.github.com/omidraha/72817ed0c6173f6c47613e3eebf03ad7

apps/__init__.py

@@ -0,0 +1,24 @@
+# noinspection PyPackageRequirements
+from pydantic import BaseModel
+
+
+class ScoreRequest(BaseModel):
+    """
+    This class define Request data model for score API
+    """
+    repo: str
+
+
+class ScoreResponse(BaseModel):
+    """
+    This class define Response data model for score API
+    """
+    repo: str
+    score: int
+
+
+class ScoreExceptionResponse(BaseModel):
+    """
+    This class define Response data model for score exception API
+    """
+    message: str

apps/score/__init__.py

@@ -0,0 +1,42 @@
+from fastapi import APIRouter, HTTPException, status
+
+from apps.score.serializer import ScoreResponse, ScoreRequest, ScoreExceptionResponse
+from settings import GITHUB_ACCESS_TOKEN
+from utility.exception import AppException
+from utility.github_api import GitHubAPI
+
+router = APIRouter()
+
+TAG_SCORE = {
+    "name": "score",
+    "description": "The main API to score",
+}
+
+
+@router.post("/score/",
+             # Hint the API docs by providing following info
+             tags=["score"],
+             response_model=ScoreResponse,
+             responses={
+                 status.HTTP_200_OK: {"model": ScoreResponse},
+                 status.HTTP_404_NOT_FOUND: {"model": ScoreExceptionResponse},
+                 status.HTTP_503_SERVICE_UNAVAILABLE: {"model": ScoreExceptionResponse}})
+async def score(data: ScoreRequest):
+    """
+    *Example:*
+
+        curl -X 'POST' 'http://127.0.0.1:8000/score/' \
+             -H 'accept: application/json' \
+             -H 'Content-Type: application/json' \
+             -d '{"repo":"python/cpython"}'
+    """
+    # @note: This may be raise ServiceException that handled globally
+    g = GitHubAPI(token=GITHUB_ACCESS_TOKEN)
+    try:
+        repo = g.get_repo(data.repo)
+    except AppException as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND,
+                            detail=e.message)
+    else:
+        return ScoreResponse(repo=repo.full_name,
+                             score=repo.score)

apps/score/serializer.py

@@ -1,17 +1,20 @@
-from fastapi import FastAPI
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+# noinspection PyPackageRequirements
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+import apps.score.view
+from utility.exception import ServiceException
 
 description = """
 ## Description
 Github Score Application to rank repositories. 🚀
 ## Available APIs
-The following is a list of available APIs. 
+The following is an list of available APIs. 
 """
 
 tags_metadata = [
-    {
-        "name": "score",
-        "description": "The main API to score",
-    },
+    apps.score.view.TAG_SCORE
 ]
 
 app = FastAPI(
@@ -22,14 +25,22 @@
 )
 
 
-@app.get("/score/", tags=["score"])
-async def score():
-    """
-    *Example:*
+# Define ServiceException as global exception handler
+@app.exception_handler(ServiceException)
+async def service_exception_handler(request: Request, exc: ServiceException):
+    return JSONResponse(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        content={"message": exc.message, },
+    )
+
 
-        curl -X 'GET' 'http://127.0.0.1:8000/score/' -H 'accept: application/json'
-    """
-    # @todo: Implement real score API
-    return {"score": 100}
+# Customize default HTTPException
+@app.exception_handler(StarletteHTTPException)
+async def http_exception_handler(request, exc):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"message": exc.detail, },
+    )
 
 
+app.include_router(apps.score.view.router)

apps/score/view.py

@@ -2,3 +2,4 @@ pytest==6.2.5
 fastapi==0.68.1
 uvicorn==0.15.0
 requests==2.26.0
+PyGithub==1.55

main.py

@@ -0,0 +1,4 @@
+import os
+# @note: To use this this service, we should set this variable
+GITHUB_ACCESS_TOKEN = os.environ.get('GITHUB_ACCESS_TOKEN')
+

requirements.txt

@@ -0,0 +1,63 @@
+from typing import Optional
+
+import pytest
+from fastapi.testclient import TestClient
+
+import settings
+from main import app
+from utility.exception import InvalidToken, RepoIsNotExist, EmptyToken
+from utility.github_api import GitHubAPI
+
+client = TestClient(app)
+
+
+@pytest.fixture(scope='class')
+def github_api():
+    return GitHubAPI(token=settings.GITHUB_ACCESS_TOKEN)
+
+
+@pytest.fixture(scope='class')
+def python_repo(github_api):
+    return github_api.get_repo('python/cpython')
+
+
+class TestGitHubAPI:
+    """
+    Test GitHubAPI class
+    """
+
+    def test_empty_token(self):
+        with pytest.raises(EmptyToken):
+            # noinspection PyTypeChecker
+            GitHubAPI(token=None)
+
+    def test_invalid_token(self):
+        g = GitHubAPI(token='invalid_token')
+        with pytest.raises(InvalidToken):
+            g.get_repo('python/cpython')
+
+    def test_invalid_repo(self, github_api):
+        with pytest.raises(RepoIsNotExist):
+            github_api.get_repo('invalid_repo/not_exist')
+
+
+class TestRepository:
+    """
+    Test Repository class
+    """
+
+    def test_get_repo(self, python_repo):
+        assert python_repo.name == 'cpython'
+        assert python_repo.full_name == 'python/cpython'
+
+    def test_forks(self, python_repo):
+        # @Note: because forks dynamically increase over the time
+        assert python_repo.forks >= 20259
+
+    def test_stars(self, python_repo):
+        # @Note: because stars dynamically increase over the time
+        assert python_repo.stars >= 40454
+
+    def test_score(self, python_repo):
+        # @Note: because score dynamically increase over the time
+        assert python_repo.score >= 80972

settings.py

@@ -0,0 +1,35 @@
+from fastapi.testclient import TestClient
+from fastapi import status
+
+from main import app
+from utility.exception import RepoIsNotExist
+
+client = TestClient(app)
+
+
+class TestScoreView:
+    """
+        Test `score` view API
+    """
+
+    def test_score_api_valid_repo(self):
+        """
+            Test `score` API while repo is valid
+        """
+        response = client.post("/score/",
+                               json={'repo': 'python/cpython', })
+
+        assert response.status_code == status.HTTP_200_OK
+        # @Note: because score dynamically increase over the time
+        assert response.json()["score"] >= 80972
+        assert response.json()["repo"] == 'python/cpython'
+
+    def test_score_api_invalid_repo(self):
+        """
+            Test `score` API while repo is not valid
+        """
+        response = client.post("/score/",
+                               json={'repo': 'invalid_repo/not_exist', })
+
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+        assert response.json()["message"] == RepoIsNotExist.message

test_main.py

@@ -0,0 +1,14 @@
+from fastapi.testclient import TestClient
+
+from main import app
+from utility.util import cal_score
+
+client = TestClient(app)
+
+
+def test_cal_score():
+    """
+        Test `cal_score` util function
+    """
+    score = cal_score(num_stars=100, num_forks=200)
+    assert score == 500