Merge pull request #528: API versioning + session serials

#528

naucse/models.py

@@ -10,8 +10,8 @@
 from arca import Task
 
 from naucse.edit_info import get_local_repo_info, get_repo_info
-from naucse.converters import Field, register_model, BaseConverter
-from naucse.converters import ListConverter, DictConverter
+from naucse.converters import Field, VersionField, register_model
+from naucse.converters import BaseConverter, ListConverter, DictConverter
 from naucse.converters import KeyAttrDictConverter, ModelConverter
 from naucse.converters import dump, load, get_converter, get_schema
 from naucse import sanitize
@@ -20,6 +20,8 @@
 
 import naucse_render
 
+API_VERSION = 0, 1
+
 # XXX: Different timezones?
 _TIMEZONE = 'Europe/Prague'
 
@@ -32,10 +34,10 @@ class NoURLType(NoURL):
 
 
 class URLConverter(BaseConverter):
- def load(self, data):
+ def load(self, data, context):
  return sanitize.convert_link('href', data)
 
- def dump(self, value):
+ def dump(self, value, context):
  return value
 
  @classmethod
@@ -156,12 +158,12 @@ class HTMLFragmentConverter(BaseConverter):
  def __init__(self, *, sanitizer=None):
  self.sanitizer = sanitizer
 
- def load(self, value, parent):
+ def load(self, value, context, *, parent):
  if self.sanitizer is None:
  return sanitize.sanitize_html(value)
  return self.sanitizer(parent, value)
 
- def dump(self, value):
+ def dump(self, value, context):
  return str(value)
 
  @classmethod
@@ -187,10 +189,10 @@ class Solution(Model):
 
 class RelativePathConverter(BaseConverter):
  """Converter for a relative path, as string"""
- def load(self, data):
+ def load(self, data, context):
  return Path(data)
 
- def dump(self, value):
+ def dump(self, value, context):
  return str(value)
 
  def get_schema(self, context):
@@ -208,7 +210,7 @@ def get_schema(self, context):
  + "relative to the repository root")
 
 @source_file_field.after_load()
-def _edit_info(self):
+def _edit_info(self, context):
  if self.source_file is None:
  self.edit_info = None
  else:
@@ -234,10 +236,10 @@ def get_pks(self):
 
 class PageCSSConverter(BaseConverter):
  """Converter for CSS for a Page"""
- def load(self, value):
+ def load(self, value, context):
  return sanitize.sanitize_css(value)
 
- def dump(self, value):
+ def dump(self, value, context):
  return value
 
  @classmethod
@@ -252,10 +254,10 @@ class LicenseConverter(BaseConverter):
  """Converter for a licence (specified as its slug in JSON)"""
  load_arg_names = {'parent'}
 
- def load(self, value, parent):
+ def load(self, value, context, *, parent):
  return parent.root.licenses[value]
 
- def dump(self, value):
+ def dump(self, value, context):
  return value.slug
 
  @classmethod
@@ -351,7 +353,7 @@ class Material(Model):
  doc="Slug of the corresponding lesson")
 
  @lesson_slug.after_load()
- def _validate_lesson_slug(self):
+ def _validate_lesson_slug(self, context):
  if self.lesson_slug and self.external_url:
  raise ValueError(
  'external_url and lesson_slug are incompatible'
@@ -416,7 +418,7 @@ class SessionTimeConverter(BaseConverter):
  to be fixed up using `_combine_session_time`.
  Converted to the full datetime on output.
  """
- def load(self, data):
+ def load(self, data, context):
  try:
  return datetime.datetime.strptime('%Y-%m-%d %H:%M:%S', data)
  except ValueError:
@@ -426,7 +428,7 @@ def load(self, data):
  time = datetime.datetime.strptime(data, '%H:%M').time()
  return time.replace(tzinfo=dateutil.tz.gettz(_TIMEZONE))
 
- def dump(self, value):
+ def dump(self, value, context):
  return value.strftime('%Y-%m-%d %H:%M:%S')
 
  @classmethod
@@ -446,10 +448,10 @@ def get_schema(cls, context):
 
 class DateConverter(BaseConverter):
  """Converter for datetime.date values (as 'YYYY-MM-DD' strings in JSON)"""
- def load(self, data):
+ def load(self, data, context):
  return datetime.datetime.strptime(data, "%Y-%m-%d").date()
 
- def dump(self, value):
+ def dump(self, value, context):
  return str(value)
 
  def get_schema(self, context):
@@ -476,6 +478,21 @@ class Session(Model):
  DateConverter(), optional=True,
  doc="The date when this session occurs (if it has a set time)",
  )
+ serial = VersionField({
+ (0, 1): Field(
+ str,
+ optional=True,
+ doc="""
+ Human-readable string identifying the session's position
+ in the course.
+ The serial is usually numeric: `1`, `2`, `3`, ...,
+ but, for example, i, ii, iii... can be used for appendices.
+ Some courses start numbering sessions from 0.
+ """
+ ),
+ # For API version 0.0, serial is generated in
+ # Course._sessions_after_load.
+ })
 
  description = Field(
  HTMLFragmentConverter(), optional=True,
@@ -490,21 +507,23 @@ class Session(Model):
  )
 
  @materials.after_load()
- def _index_materials(self):
+ def _index_materials(self, context):
  set_prev_next(m for m in self.materials if m.lesson_slug)
 
  pages = Field(
  DictConverter(SessionPage, key_arg='slug'),
  optional=True,
  doc="The session's cover pages")
  @pages.after_load()
- def _set_pages(self):
+ def _set_pages(self, context):
  if not self.pages:
  self.pages = {}
  for slug in 'front', 'back':
  if slug not in self.pages:
- page = get_converter(SessionPage).load(
- {}, slug=slug, parent=self,
+ page = load(
+ SessionPage,
+ {'api_version': [0, 0], 'session-page': {}},
+ slug=slug, parent=self,
  )
  self.pages[slug] = page
 
@@ -514,7 +533,7 @@ def _set_pages(self):
  doc="Time when this session takes place.")
 
  @time.after_load()
- def _fix_time(self):
+ def _fix_time(self, context):
  if self.time is None:
  self.time = {}
  else:
@@ -546,10 +565,10 @@ def _fix_time(self):
 
 class AnyDictConverter(BaseConverter):
  """Converter of any JSON-encodable dict"""
- def load(self, data):
+ def load(self, data, context):
  return data
 
- def dump(self, value):
+ def dump(self, value, context):
  return value
 
  @classmethod
@@ -568,13 +587,13 @@ def time_from_string(time_string):
 
 class TimeIntervalConverter(BaseConverter):
  """Converter for a time interval, as a dict with 'start' and 'end'"""
- def load(self, data):
+ def load(self, data, context):
  return {
  'start': time_from_string(data['start']),
  'end': time_from_string(data['end']),
  }
 
- def dump(self, value):
+ def dump(self, value, context):
  return {
  'start': value['start'].strftime('%H:%M'),
  'end': value['end'].strftime('%H:%M'),
@@ -673,14 +692,19 @@ def _default_lessons(self):
  doc="Individual sessions")
 
  @sessions.after_load()
- def _sessions_after_load(self):
+ def _sessions_after_load(self, context):
  set_prev_next(self.sessions.values())
 
  for session in self.sessions.values():
  for material in session.materials:
  if material.lesson_slug:
  self._requested_lessons.add(material.lesson_slug)
 
+ if context.version < (0, 1) and len(self.sessions) > 1:
+ # Assign serials to sessions (numbering from 1)
+ for serial, session in enumerate(self.sessions.values(), start=1):
+ session.serial = str(serial)
+
  source_file = source_file_field
 
  start_date = Field(
@@ -734,7 +758,7 @@ def load_remote(cls, slug, *, parent, link_info):
  doc="Slug of the course this derives from (deprecated)")
 
  @derives.after_load()
- def _set_base_course(self):
+ def _set_base_course(self, context):
  key = f'courses/{self.derives}'
  try:
  self.base_course = self.root.courses[key]
@@ -819,7 +843,7 @@ def freeze(self):
 
 class AbbreviatedDictConverter(DictConverter):
  """Dict that only shows URLs to its items when dumped"""
- def dump(self, value):
+ def dump(self, value, context):
  return {
  key: {'$ref': v.get_url('api', external=True)}
  for key, v in value.items()
@@ -1034,7 +1058,11 @@ def load_licenses(self, path):
  with (licence_path / 'info.yml').open() as f:
  info = yaml.safe_load(f)
  slug = licence_path.name
- license = get_converter(License).load(info, parent=self, slug=slug)
+ license = load(
+ License,
+ {'api_version': [0, 0], 'license': info},
+ parent=self, slug=slug,
+ )
  self.licenses[slug] = license
 
  def get_course(self, slug):

naucse/templates/course.html

@@ -25,8 +25,8 @@ <h2>{{ course.subtitle }}</h2>
 
 <div class="section{{ loop.index }}">
  <h4>
- {% if course.sessions|length > 1 %}
- Lekce {{ loop.index }} –
+ {% if session.serial != None %}
+ Lekce {{ session.serial }} –
  {% endif %}
  <a href="{{ session.get_url() }}">
  {{ session.title }}

naucse/views.py

@@ -399,12 +399,14 @@ def schema(model_slug, is_input):
  cls = models.models[model_slug]
  except KeyError:
  abort(404)
- return jsonify(models.get_schema(cls, is_input=is_input))
+ return jsonify(models.get_schema(
+ cls, is_input=is_input, version=models.API_VERSION,
+ ))
 
 
 @app.route('/v0/naucse.json')
 def api():
- return jsonify(models.dump(g.model))
+ return jsonify(models.dump(g.model, version=models.API_VERSION))
 
 
 @app.route('/v0/years/<int:year>.json')
@@ -413,7 +415,7 @@ def run_year_api(year):
  run_year = g.model.run_years[year]
  except KeyError:
  abort(404)
- return jsonify(models.dump(run_year))
+ return jsonify(models.dump(run_year, version=models.API_VERSION))
 
 
 @app.route('/v0/<course:course_slug>.json')
@@ -422,4 +424,4 @@ def course_api(course_slug):
  course = g.model.courses[course_slug]
  except KeyError:
  abort(404)
- return jsonify(models.dump(course))
+ return jsonify(models.dump(course, version=models.API_VERSION))

test_naucse/conftest.py

@@ -82,6 +82,15 @@ def assert_yaml_dump(data, filename):
  assert data == expected
 
 
+@pytest.fixture(params=((0, 0), (0, 1)))
+def assert_model_dump(request):
+ version = request.param
+ def _assert(model, filename):
+ filename += '.v{}.{}.yaml'.format(*version)
+ assert_yaml_dump(models.dump(model, version=version), filename)
+ return _assert
+
+
 def add_test_course(model, slug, data):
  model.add_course(models.load(
  models.Course,

test_naucse/fixtures/course-data/course-v0.1.yml

@@ -0,0 +1,15 @@
+course:
+ api_version: [0, 1]
+ course:
+ title: A course loaded from API version 0.1
+ subtitle: Suitable for testing only.
+ source_file: courses/complex/info.yml
+ sessions:
+ - slug: first
+ title: First
+ serial: '1'
+ - slug: second
+ title: Second
+ serial: '2'
+ - slug: special
+ title: Special