codegrade 16.1.91__tar.gz → 17.0.0__tar.gz

codegrade-17.0.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: codegrade
+Version: 17.0.0
+Summary: A client library for accessing CodeGrade
+Project-URL: Documentation, https://python.api.codegrade.com
+License-Expression: AGPL-3.0-only OR BSD-3-Clause-Clear
+Requires-Python: <4.0,>=3.8.0
+Requires-Dist: httpx<1.0.0,>=0.19.0
+Requires-Dist: python-dateutil<3,>=2.8.1
+Requires-Dist: structlog>=20.1.0
+Requires-Dist: typing-extensions<5,>=4.13.2
+Requires-Dist: validate-email~=1.3
+Description-Content-Type: text/markdown
+
+# CodeGrade API
+
+This library makes it easier to use the CodeGrade API. Its API allows you to
+automate your usage of CodeGrade. We are currently still busy documenting the
+entire API, but everything that is possible in the UI of CodeGrade is also
+possible through the API.
+## Installation
+You can install the library through [pypi](https://pypi.org/), simply run
+`python3 -m pip install codegrade`. If you want to get a dev version with support
+for the latest features, simply email [support@codegrade.com](mailto:support@codegrade.com)
+and we'll provide you with a dev version.
+## Usage
+First, create a client:
+
+```python
+import codegrade
+
+# Don't store your password in your code!
+with codegrade.login(
+    username='my-username',
+    password=os.getenv('CG_PASSWORD'),
+    tenant='My University',
+) as client:
+    pass
+
+# Or supply information interactively.
+with codegrade.login_from_cli() as client:
+    pass
+```
+
+Now call your endpoint and use your models:
+
+```python
+from codegrade.models import PatchCourseData
+
+courses = client.course.get_all()
+for course in courses:
+    client.course.patch(
+        PatchCourseData(name=course.name + ' (NEW)'),
+        course_id=course.id,
+    )
+
+# Or, simply use dictionaries.
+for course in courses:
+    client.course.patch(
+        {"name": course.name + ' (NEW)'},
+        course_id=course.id,
+    )
+```
+
+For the complete documentation go to
+https://python.api.codegrade.com.
+## Backwards compatibility
+CodeGrade is constantly upgrading its API, but we try to minimize backwards
+incompatible changes. We'll announce every backwards incompatible change in the
+[changelog](http://codegrade.com/changelog). A new version of the API
+client is released with every release of CodeGrade, which is approximately every
+month. To upgrade simply run `pip install --upgrade codegrade`.
+## Supported python versions
+We support python 3.6 and above, `pypy` is currently not tested but should work
+just fine.
+## License
+The library is licensed under AGPL-3.0-only or BSD-3-Clause-Clear.

codegrade-17.0.0/docs/_static/custom_style.css

@@ -0,0 +1,45 @@
+html {
+	overflow: auto !important;
+}
+
+body {
+	overflow-x: auto;
+}
+
+@media (min-width: 67.001em) {
+	.sidebar-drawer {
+		width: auto !important;
+		min-width: 23em !important;
+	}
+
+	.sidebar-container {
+		width: auto !important;
+		min-width: 23em !important;
+	}
+}
+
+.content { width: auto !important }
+.highlight .nn { text-decoration: none !important }
+
+.toggle .header {
+	display: block;
+	clear: both;
+	cursor: pointer;
+}
+
+.toggle .header p {
+	display: inline-block;
+	margin-left: .5em;
+}
+
+.toggle .header::before {
+	content: " ▶";
+}
+
+.toggle .header.open::before {
+	content: " ▼";
+}
+
+.sidebar-logo {
+	max-width: 50%;
+}

codegrade-17.0.0/docs/_static/images/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 143.76 153.13"><defs><style>.cls-1{fill:#45617d;}</style></defs><title>codegrade-small</title><g id="Layer_2" data-name="Layer 2"><g id="Layer_1-2" data-name="Layer 1"><path class="cls-1" d="M107.46,83.53a38.44,38.44,0,0,0-8.8-7,18.94,18.94,0,0,0-9.4-2.6,27.41,27.41,0,0,0-20.7,8.8,27,27,0,0,0-5.6,9.2,31.64,31.64,0,0,0,0,21.6,27,27,0,0,0,5.6,9.2,27.41,27.41,0,0,0,20.7,8.8,23.81,23.81,0,0,0,10.4-2.3,22.66,22.66,0,0,0,8.2-6.7l16,17.2a36.92,36.92,0,0,1-8.3,6.2,57.38,57.38,0,0,1-9.5,4.2,59.17,59.17,0,0,1-9.2,2.3,50.32,50.32,0,0,1-7.6.7,57.62,57.62,0,0,1-20.4-3.6,48.87,48.87,0,0,1-16.6-10.2,48.3,48.3,0,0,1-11.1-15.9,50.66,50.66,0,0,1-4.1-20.7A50.66,50.66,0,0,1,41.16,82a48.3,48.3,0,0,1,11.1-15.9c4.66-4.4,10.91-1.54,17.31-3.94s15.3-1.14,24-4c5.82-1.92,8-4.69,14.19-2.36a42.05,42.05,0,0,1,16.3,11.1Z"/><g id="surface1"><path class="cls-1" d="M68.82,0A3,3,0,0,0,68,.3L1.68,31.44A2.85,2.85,0,0,0,0,34.37a2.88,2.88,0,0,0,2.29,2.46l16.45,3.52c-.13.22-.34.38-.48.6-2.92,4.76-4,11-3.68,19.74a7.62,7.62,0,0,0,1.62,13.66c0,19.74-10.77,27.64-10.57,29.3.1.85,9.66,4.69,11.82,4.43,3.32-.39,10.66-6.9,9.21-19.12A91.41,91.41,0,0,0,23.3,72.6a7.07,7.07,0,0,0-1.78-12c-.29-8,.68-12.74,2.66-16,2.29-3.76,6.42-6.36,12.68-9.88l1.19-.69c.09,0,.08-.16.16-.2,1.09-.58,2.23-1.17,3.09-1.64,4.1-2.28,7.5-4,10.63-5.62.94-.5,1.51-.91,2.38-1.38,2.83-1.49,4.87-2.53,6.87-3.54.75-.39,1.23-.62,1.89-.95,4.54-2.27,6.49-3.11,6.55-3.14a3.43,3.43,0,1,1,2.92,6.21c-.13.06-7.81,3.4-27.78,14.57-1.29.72-2.61,1.27-3.79,1.91-2.37,1.28-4.33,2.44-6,3.43l39,8a3.18,3.18,0,0,0,.92.07,3.23,3.23,0,0,0,.88-.28l66.27-31.14a2.88,2.88,0,0,0,1.66-2.93,2.86,2.86,0,0,0-2.3-2.46L69.74.09A2.82,2.82,0,0,0,68.82,0Zm51.25,39.13L78.48,58.62a10.22,10.22,0,0,1-5.39.63L29.57,50.18a23.47,23.47,0,0,0-.1,8.4c2.93,1.24,6,4.12,6.6,9.6a11,11,0,0,1-2.36,7.75c7,6.47,24.77,9.64,44.93,7.26,25.4-3,45-13.63,43.83-23.75Z"/></g></g></g></svg>

codegrade-17.0.0/docs/_static/toggle.js

@@ -0,0 +1,8 @@
+$(document).ready(function() {
+	$(".toggle > *").hide();
+	$(".toggle .header").show();
+	$(".toggle .header").click(function() {
+		$(this).parent().children().not(".header").slideToggle(400);
+		$(this).parent().children(".header").toggleClass("open");
+	});
+});

codegrade-17.0.0/docs/clients/AuthenticatedClient.rst

@@ -0,0 +1,42 @@
+AuthenticatedClient
+===================
+
+.. currentmodule:: codegrade.client
+
+.. autoclass:: AuthenticatedClient
+   :members: get, get_from_cli, get_with_token
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :nosignatures:
+
+      ~AuthenticatedClient.get
+      ~AuthenticatedClient.get_from_cli
+      ~AuthenticatedClient.get_with_token
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~AuthenticatedClient.about
+      ~AuthenticatedClient.assignment
+      ~AuthenticatedClient.auto_test
+      ~AuthenticatedClient.comment
+      ~AuthenticatedClient.course
+      ~AuthenticatedClient.course_price
+      ~AuthenticatedClient.file
+      ~AuthenticatedClient.git_provider
+      ~AuthenticatedClient.group
+      ~AuthenticatedClient.login_link
+      ~AuthenticatedClient.lti
+      ~AuthenticatedClient.oauth_provider
+      ~AuthenticatedClient.permission
+      ~AuthenticatedClient.site_settings
+      ~AuthenticatedClient.snippet
+      ~AuthenticatedClient.submission
+      ~AuthenticatedClient.task_result
+      ~AuthenticatedClient.tenant
+      ~AuthenticatedClient.transaction
+      ~AuthenticatedClient.user
+      ~AuthenticatedClient.user_setting

codegrade-17.0.0/docs/conf.py

@@ -0,0 +1,136 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+import json
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+from datetime import date
+
+cur_dir = os.path.dirname(__file__)
+
+# -- Project information -----------------------------------------------------
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# General information about the project.
+project = "codegrade"
+copyright = str(date.today().year) + ", CodeGrade"
+author = "CodeGrade Team"
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = "17.0.0"
+# The full version, including alpha/beta/rc tags.
+release = version
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+    "sphinx_autodoc_typehints",
+    "m2r2",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "",
+    "psef_api/psef.rst",
+    "build/*",
+    "readme/*",
+]
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "CodeGradedoc"
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_css_files = ["custom_style.css"]
+html_js_files = ["toggle.js"]
+
+html_favicon = "_static/favicon/favicon.ico"
+html_logo = "_static/images/logo.svg"
+html_title = "CodeGrade 17.0.0"
+
+# -- Extension configuration -------------------------------------------------
+
+autodoc_default_options = {
+    "undoc-members": True,
+    "exclude-members": "__init__, __new__",
+}
+autoclass_content = "init"
+autodoc_class_signature = "separated"
+autodoc_member_order = "bysource"
+autodoc_typehints = "both"
+
+autosummary_generate = True
+
+add_module_names = False
+
+set_type_checking_flag = False
+typehints_fully_qualified = False
+always_document_param_types = False
+typehints_document_rtype = False
+
+# -- Options for intersphinx extension ---------------------------------------
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+os.environ["CG_EAGERIMPORT"] = "True"
+os.environ["CG_GENERATING_DOCS"] = "True"

codegrade-17.0.0/docs/examples/export_feedback.rst

@@ -0,0 +1,176 @@
+:hide-toc: true
+
+
+Export Feedback
+===============
+
+
+Use this script to export inline comments in any way you want.
+The complete script is available at the :ref:`end of the page <complete-feedback-script>`.
+
+
+Breakdown
+---------
+
+
+Before any operation can be executed, we need to import codegrade and
+authenticate with the server.
+
+To authenticate, we have to pass our username, password and to which
+tenant we are connecting. It is best practice to not store your
+password inside the script. Either have the user input it or add it
+to your environment while working.
+
+.. code-block:: python
+
+   import os
+   import codegrade
+
+   client = codegrade.login(
+      username='username',
+      password=os.getenv('CG_PASSWORD')
+      tenant='Tenant Name')
+
+Once we receive a client from the server, we are able to query it for
+the data we need. In this case, we are trying to access the submissions
+of our assignment.
+
+The first step to do this is getting the assignment's ID. You could put
+it manually in the script, but we provide an interactive utility that
+makes this process easier: :func:`codegrade.utils.select_from_list`.
+
+As the user may insert an invalid value, we need to check that there
+is a value to use to begin with. For this reason, we offer another
+utility function, :func:`codegrade.utils.value_or_exit`. You can
+specify also a custom error message to give more information to the
+user.
+
+To showcase the entire workflow, we will use this to acquire first the
+course's ID, then the assignment's ID, so that you do not need to know
+the actual ID, just the course's and assignment's names.
+
+The utility takes three parameters:
+
+- A prompt for the user, to describe them what they are seeing
+- A list from which to choose
+- What each item should show
+
+Let's show the user the course's names. To do so, we will use the
+data attached with the :class:`.ExtendedCourse`, in particular the
+``name`` property.
+
+.. code-block:: python
+
+   all_courses = client.course.get_all()
+   course = codegrade.utils.value_or_exit(
+      codegrade.utils.select_from_list(
+         'Select a course',
+         all_courses,
+         lambda c: c.name))
+
+We can now repeat this process to get the assignment's id as well.
+We do not need to query the server for the assignments, as we already
+have them in ``course``.
+
+.. code-block:: python
+
+   assignment = codegrade.utils.value_or_exit(
+      codegrade.utils.select_from_list(
+         'Select an assignment',
+         course.assignments,
+         lambda a: a.name))
+
+Now that we have an assignment, we can query the server for all its
+submissions using the :class:`.AssignmentService` of the client.
+
+We can also specify some further information with the query, for
+example if we want all the submissions or only the latest. See
+:meth:`.AssignmentService.get_all_submissions` for the documentation.
+
+We will only get the latest submissions.
+
+.. code-block:: python
+
+   submissions = client.assignment.get_all_submissions(
+      assignment_id=assignment.id,
+      latest_only=True)
+
+We can now get the actual feedback and print it using the
+:class:`.SubmissionService`.
+
+As we are not interested in the replies, we will not get them. We
+can do this using the parameters for :meth:`.SubmissionService.get_feedback`.
+
+Finally we can loop through the files, and then each of the
+comments and print them.
+
+.. code-block:: python
+
+   for submission in submissions:
+      print(f'\nSubmission by {submission.user.name}')
+      feedback = client.submission.get_feedback(
+         submission_id=submission.id,
+         with_replies=False)
+
+      for file_id, comments in feedback.user.items():
+         for author_id, comment in comments.items():
+            author = feedback.authors[file_id][author_id].name
+            print(f'{author}: {comment}')
+
+
+.. _complete-feedback-script:
+
+Complete Feedback script
+------------------------
+
+.. container:: toggle
+
+   .. container:: header
+
+      Click here to see the copy-friendly script
+
+   .. code-block:: python
+
+        import os
+        import codegrade
+
+        # Login to CodeGrade
+        client = codegrade.login(
+            username='username',
+            password=os.getenv('CG_PASSWORD')
+            tenant='Tenant Name')
+
+        # Get all courses and select the desired one
+        all_courses = client.course.get_all()
+        course = codegrade.utils.value_or_exit(
+            codegrade.utils.select_from_list(
+                'Select a course',
+                all_courses,
+                lambda c: c.name))
+
+        # Select the desired assignment
+        assignment = codegrade.utils.value_or_exit(
+            codegrade.utils.select_from_list(
+                'Select an assignment',
+                course.assignments,
+                lambda a: a.name))
+
+        # Get all submissions for given assignment
+        submissions = client.assignment.get_all_submissions(
+            assignment_id=assignment.id,
+            latest_only=True)
+
+        # Loop over all submissions and print all inline comments
+        for submission in submissions:
+            print(f'\nSubmission by {submission.user.name}')
+            feedback = client.submission.get_feedback(
+                submission_id=submission.id,
+                with_replies=False)
+
+            # Loop over all individual files in the submission
+            for file_id, comments in feedback.user.items():
+
+                # Loop over all comments per file in submission and print
+                for author_id, comment in comments.items():
+                    author = feedback.authors[file_id][author_id].name
+                    print(f'{author}: {comment}')

codegrade-17.0.0/docs/examples/export_progress.rst

@@ -0,0 +1,136 @@
+:hide-toc: true
+
+
+Export Student Progress
+=======================
+
+
+Use this script to export the progress over all submissions done by each
+individual student. The complete script is available at the :ref:`end of the page <complete-progress-script>`.
+
+
+.. note::
+   This example presupposes you have read the previous example. If you have not
+   please read `Export Feedback <export_feedback.html>`_ first.
+
+
+Breakdown
+---------
+
+
+Before querying the server, we need to login. A different way of logging
+in, that is potentially more secure if multiple users need to use the
+script, is by asking for the credentials in input. Fortunately, our
+package comes equipped with such a utility, :func:`.codegrade.login_from_cli`.
+
+.. code-block:: python
+
+    import codegrade
+
+    client = codegrade.login_from_cli()
+
+We now need a user's id to get the information we need. We will use
+:func:`.codegrade.utils.select_from_list`. We will first select a course
+and then one of the users from the given course.
+
+There is a catch, as :meth:`.CourseService.get_all_users` returns a
+:class:`.Union` of both type :class:`.User` and :class:`.UserCourse`.
+We will solve this by mapping objects of the latter type to the former
+through :attr:`.UserCourse.user`.
+
+.. code-block:: python
+
+    all_courses = client.course.get_all()
+    course = codegrade.utils.value_or_exit(
+        codegrade.utils.select_from_list(
+            'Select a course',
+            all_courses,
+            lambda c: c.name))
+
+    all_users = list(map(
+        lambda u: u if isinstance(u, codegrade.models.user.User) else u.user,
+        client.course.get_all_users(course_id=course.id)))
+    user = codegrade.utils.value_or_exit(
+        codegrade.utils.select_from_list(
+            'Select a user',
+            all_users,
+            lambda u: f'{u.name} ({u.username})'))
+
+Now we can get all the users submissions through :meth:`.AssignmentService.get_submissions_by_user`.
+As such, we first need to select an assignment for which we want the
+user's progress.
+
+.. code-block:: python
+
+    assignment = codegrade.utils.value_or_exit(
+        codegrade.utils.select_from_list(
+            'Select an assignment',
+            course.assignments,
+            lambda a: a.name))
+
+    submissions = client.assignment.get_submissions_by_user(
+        assignment_id=assignemnt.id,
+        user_id=user.id)
+
+Now we can finally print the grades for the various submissions of
+the given user for the given assignment.
+
+.. code-block:: python
+
+    for submission in submissions:
+        print(f'Submission uploaded: {submission.created_at.isoformat()}'
+              f' | Grade: {submission.grade}')
+
+
+.. _complete-progress-script:
+
+Complete Student Progress script
+--------------------------------
+
+.. container:: toggle
+
+   .. container:: header
+
+      Click here to see the copy-friendly script
+
+   .. code-block:: python
+
+        import codegrade
+
+        # Login to CodeGrade
+        client = codegrade.login_from_cli()
+
+        # Get all courses and select the desired one
+        all_courses = client.course.get_all()
+        course = codegrade.utils.value_or_exit(
+            codegrade.utils.select_from_list(
+                'Select a course',
+                all_courses,
+                lambda c: c.name))
+
+        # Get all course's users, map them to user types and select the desired one
+        all_users = list(map(
+            lambda u: u if isinstance(u, codegrade.models.user.User) else u.user,
+            client.course.get_all_users(course_id=course.id)))
+        user = codegrade.utils.value_or_exit(
+            codegrade.utils.select_from_list(
+                'Select a user',
+                all_users,
+                lambda u: f'{u.name} ({u.username})'))
+
+        # Select desired assignment from course
+        assignment = codegrade.utils.value_or_exit(
+            codegrade.utils.select_from_list(
+                'Select an assignment',
+                course.assignments,
+                lambda a: a.name))
+
+        # Get all user's submissions for the given assignment
+        submissions = client.assignment.get_submissions_by_user(
+            assignment_id=assignment.id,
+            user_id=user.id)
+
+        # Loop over user's submissions and print the acheived grade
+        for submission in submissions:
+            print(f'Submission uploaded: {submission.created_at.isoformat()}'
+                  f' | Grade: {submission.grade}')