Backend restructuring issue tracker

[aaron-schroeder]

Realized "Activity" isn't the center of the package - the ability to create file-specific dataframe formats is.

• Create a low-level document-based API #27 (moved to Package structure issue tracker XPathletics#1)
• Existing API classes and functions (v0.0.24 and earlier) that will be deprecated
  • Deprecation warnings
  • Deprecation docstring changes

Notes and musings

• I originally thought of arranging the backend like SQLAlchemy, but then realized that a general standalone package would be called for. Package structure issue tracker XPathletics#1
• *Factory API -> top-level Activity-like classes
  • GpxTrk/GpxRte/TcxActivity/...
    1. Create manually with XMLSchemaFactory (name pending - might describe wrong thing)
    2. Create XsdSchemaParser to automatically build such a structure from a schema file.
  • FitActivity
    1. io.fit uses fitparse to make a df structured like a fit file (index is msg number)
    2. (someday, maybe) create FitProfileParser if fitparse presents a limitation in the future
  • StravaActivity
    1. Create manually with JsonSchemaFactory
    2. Create a json schema parser, if such a standard schema is defined.
  • Other top-level classes I hadn't even thought of:
    • Race
      • Based on the structure of athlinks results
      • Column level 1: Fields.
        - split name (row index?)
        - cumulative distance (dtype='pint[m]')
      • Column level 2: athlete name (validator: any str)
      • Column level 3: age group (validator: 2-elem tuple with (bound_lo, bound_hi))
      • Column level 4: gender (validator: must belong to a list of str, eg ['M', 'F', 'NB'])
      • (Column level 5: inbound/outbound (validator: 1 of 2 choices))
      • place = rank(timestamp, filter_by=['gender', 'age_group'], start=1) -> race.place(athlete_nm, filters=['gender'], split='Halfmoon')
      • split_time = value(time_offset, index_by='Lap')
• ActivityMixin
  • Migrate most existing Activity functionality here
  • Modify still-relevant Activity tests to look for FitActivity, TcxActivity, GpxTrk classes which are themselves built using other parts of the public API.
• Row and column index classes: either IndexLabel or {RowLabel, ColLabel}
  • ColLabel(name='source', options=['strava', 'file']) (isn't this really a multiindex level descriptor though?)
  • ColLabel(name='timestamp', dtype=tzdtype)
    • tzdtype = pd.DatetimeTZDtype(tz='UTC')) or pd.DatetimeTZDtype(tz='dateutil/US/Central'))
  • ColLabel(name='DistanceMeters', dtype='pint[m]', restrictions=['flat_or_increasing', '>0'])
    • restrictions kwarg is just a sketch of a catch-all functionality. Inspired by something else that escapes me rn.
  • RowLabel(name='Lap', restrictions=['start_at_0', 'flat_or_plus_1'])