ft-tui 0.2.2__py3-none-any.whl

ft_tui/__init__.py

@@ -0,0 +1,3 @@
+"""42TUI: terminal workspace for École 42 students."""
+
+__version__ = "0.1.0"

ft_tui/api/__init__.py

@@ -0,0 +1,8 @@
+"""42TUI API providers."""
+from .client_interface import ProjectProvider
+from .http_client import HttpProjectProvider
+__all__=['ProjectProvider','HttpProjectProvider']
+
+from .keychain import CredentialStore,SecureStoreError
+from .oauth_client import DeviceCredentials,OAuthClient,PairingResult,PairingStart
+__all__ += ['CredentialStore','SecureStoreError','DeviceCredentials','OAuthClient','PairingResult','PairingStart']

ft_tui/api/activity_types.py

@@ -0,0 +1,120 @@
+"""Validate account-owned project activity and discard unrecognized upstream fields."""
+from datetime import datetime
+from math import isfinite
+from .catalog_types import positive
+
+
+def require(condition):
+    if not condition:
+        raise ValueError('Invalid project activity response')
+
+
+def text(value):
+    require(value is None or isinstance(value, str) and len(value) <= 1048576)
+    return value
+
+
+def date(value):
+    if value is not None:
+        require(isinstance(value, str))
+        try:
+            require(datetime.fromisoformat(value.replace('Z', '+00:00')).tzinfo is not None)
+        except (ValueError, OverflowError):
+            raise ValueError('Invalid project activity timestamp') from None
+    return value
+
+
+def mark(value):
+    require(value is None or type(value) in (int, float) and isfinite(value))
+    return value
+
+
+def source(value):
+    require(isinstance(value, dict))
+    require(value.get('status') in {'available', 'unavailable', 'unknown'} and type(value.get('stale')) is bool)
+    at = date(value.get('collected_at'))
+    require(value['status'] != 'available' or at is not None)
+    reason = value.get('reason_code')
+    require(reason in (None, 'permission_denied'))
+    return {'status': value['status'], 'stale': value['stale'], 'collected_at': at,
+            **({'reason_code': reason} if reason else {})}
+
+
+def rows(value):
+    require(isinstance(value, list) and len(value) <= 10000)
+    require(all(isinstance(x, dict) and positive(x.get('id')) for x in value))
+    require(len({x['id'] for x in value}) == len(value))
+    return value
+
+
+def identity(value, project_id, scope, account_id):
+    require(positive(project_id) and isinstance(value, dict))
+    require(value.get('account_id') == account_id and value.get('project_id') == project_id)
+    require(value.get('context') == scope.params())
+    return {'account_id': account_id, 'project_id': project_id, 'context': scope.params()}
+
+
+def project_activity(value, project_id, scope, account_id, *, subject_user_id=None):
+    result = identity(value, project_id, scope, account_id)
+    require(value.get('current_team_id') is None or positive(value['current_team_id']))
+    teams = []
+    for team in rows(value.get('teams')):
+        require(team.get('project_id') == project_id)
+        require(isinstance(team.get('name'), str) and isinstance(team.get('status'), str))
+        require(team.get('validated') is None or type(team['validated']) is bool)
+        members = []
+        for member in rows(team.get('members')):
+            require(isinstance(member.get('login'), str) and type(member.get('leader')) is bool)
+            members.append({k: member[k] for k in ('id', 'login', 'leader')})
+        require(any(str(m['id']) == (subject_user_id or account_id) for m in members))
+        teams.append({'id': team['id'], 'project_id': project_id, 'name': team['name'], 'status': team['status'],
+                      'validated': team.get('validated'), 'final_mark': mark(team.get('final_mark')),
+                      'repo_url': text(team.get('repo_url')), 'members': members,
+                      **{k: date(team.get(k)) for k in ('created_at', 'locked_at', 'closed_at')}})
+    return {**result, 'current_team_id': value.get('current_team_id'), 'teams': teams, 'source': source(value.get('source'))}
+
+
+def team_evaluations(value, project_id, team_id, scope, account_id):
+    result = identity(value, project_id, scope, account_id)
+    require(positive(team_id) and value.get('team_id') == team_id)
+    groups = {}
+    for name in ('peer', 'automated'):
+        group = value.get(name)
+        require(isinstance(group, dict))
+        items = []
+        for item in rows(group.get('items')):
+            clean = {'id': item['id'], 'final_mark': mark(item.get('final_mark')), 'comment': text(item.get('comment'))}
+            if name == 'automated':
+                require(isinstance(item.get('name'), str))
+                clean.update(name=item['name'], created_at=date(item.get('created_at')))
+            else:
+                require(item.get('team_id') is None or item['team_id'] == team_id)
+                require(type(item.get('details_unavailable', False)) is bool)
+                corrector = item.get('corrector')
+                require(corrector is None or isinstance(corrector, dict) and positive(corrector.get('id')) and isinstance(corrector.get('login'), str))
+                require(type(item.get('participants_hidden')) is bool)
+                flag = item.get('flag')
+                require(flag is None or isinstance(flag, dict) and isinstance(flag.get('name'), str) and (flag.get('positive') is None or type(flag['positive']) is bool))
+                feedbacks = item.get('feedbacks')
+                require(isinstance(feedbacks, list) and len(feedbacks) <= 1000)
+                require(all(isinstance(f, dict) for f in feedbacks))
+                clean.update(details_unavailable=item.get('details_unavailable', False), team_id=item.get('team_id'), corrector={k: corrector[k] for k in ('id', 'login')} if corrector else None,
+                             participants_hidden=item['participants_hidden'], begin_at=date(item.get('begin_at')),
+                             filled_at=date(item.get('filled_at')), feedback=text(item.get('feedback')),
+                             feedback_rating=mark(item.get('feedback_rating')), flag=flag,
+                             feedbacks=[{'comment': text(f.get('comment')), 'rating': mark(f.get('rating'))} for f in feedbacks])
+            items.append(clean)
+        groups[name] = {'items': items, 'source': source(group.get('source'))}
+    return {**result, 'team_id': team_id, **groups}
+
+
+def friend_activity(value, project_id, attempt_id, user_id, scope, account_id):
+    require(isinstance(value,dict) and value.get('subject_user_id')==user_id and value.get('attempt_id')==attempt_id)
+    clean=project_activity(value,project_id,scope,account_id,subject_user_id=user_id)
+    require(clean['current_team_id'] is None or any(team['id']==clean['current_team_id'] for team in clean['teams']))
+    return {**clean,'subject_user_id':user_id,'attempt_id':attempt_id}
+
+
+def friend_evaluations(value, project_id, attempt_id, user_id, team_id, scope, account_id):
+    require(isinstance(value,dict) and value.get('subject_user_id')==user_id and value.get('attempt_id')==attempt_id)
+    return {**team_evaluations(value,project_id,team_id,scope,account_id),'subject_user_id':user_id,'attempt_id':attempt_id}

ft_tui/api/campus_types.py

@@ -0,0 +1,22 @@
+"""Validate the shared public campus directory before caching it locally."""
+from .catalog_types import positive
+
+
+def campus_directory(value):
+    rows = value.get('campuses') if isinstance(value, dict) else None
+    if not isinstance(rows, list) or len(rows) > 10000:
+        raise ValueError('Invalid campus directory')
+    result, ids = [], set()
+    for row in rows:
+        if not isinstance(row, dict) or not positive(row.get('id')) or row['id'] in ids:
+            raise ValueError('Invalid campus directory')
+        if not isinstance(row.get('name'), str) or not row['name'].strip() or len(row['name']) > 512:
+            raise ValueError('Invalid campus directory')
+        for field in ('country', 'city'):
+            if row.get(field) is not None and (not isinstance(row[field], str) or len(row[field]) > 512):
+                raise ValueError('Invalid campus directory')
+        if row.get('active') is not None and type(row['active']) is not bool:
+            raise ValueError('Invalid campus directory')
+        ids.add(row['id'])
+        result.append({key: row.get(key) for key in ('id', 'name', 'country', 'city', 'active')})
+    return result

ft_tui/api/catalog_types.py

@@ -0,0 +1,37 @@
+"""Public catalog DTO validation, independent from local ORM identities."""
+from dataclasses import dataclass,asdict
+import math
+@dataclass(frozen=True)
+class CatalogScope:
+    cursus_id:int
+    campus_id:int
+    def params(self):return asdict(self)
+
+def positive(value):return type(value) is int and value>0
+
+def project_summary(value):
+    if not isinstance(value,dict) or not positive(value.get('project_id')):
+        raise ValueError('Invalid official project ID')
+    for field in ('slug','name','kind'):
+        if not isinstance(value.get(field),str) or not value[field]:raise ValueError('Invalid catalog project')
+    for field in ('xp','rank'):
+        n=value.get(field)
+        if n is not None and (type(n) is not int or n<0):raise ValueError('Invalid catalog number')
+    if value.get('track') not in (None,'old','new','shared') or value.get('section') not in ('common-core','specialization','other'):
+        raise ValueError('Invalid catalog classification')
+    if value.get('duration') is not None and not isinstance(value['duration'],str):raise ValueError('Invalid duration')
+    if value.get('project_mode','unknown') not in {'solo','group','unknown'}:raise ValueError('Invalid project mode')
+    if value.get('team_size') is not None and not positive(value['team_size']):raise ValueError('Invalid team size')
+    fields=('team_size','project_mode','project_id','slug','name','kind','xp','duration','rank','track','section','section_source',
+            'evidence_status','snapshot_id','description','rules','clauses','visual_links','branches',
+            'web_node_id','coordinates')
+    return {field:value[field] for field in fields if field in value}
+
+def catalog_page(value,scope):
+    if not isinstance(value,dict) or not isinstance(value.get('items'),list) or len(value['items'])>100 or not isinstance(value.get('snapshot_id'),str):raise ValueError('Invalid catalog page')
+    meta=value.get('meta',{})
+    if meta.get('cursus_id')!=scope.cursus_id or meta.get('campus_id')!=scope.campus_id:raise ValueError('Catalog scope mismatch')
+    if value.get('next_cursor') is not None and not isinstance(value['next_cursor'],str):raise ValueError('Invalid catalog cursor')
+    clean={**value,'items':[project_summary(x) for x in value['items']]}
+    if len({x['project_id'] for x in clean['items']})!=len(clean['items']):raise ValueError('Duplicate catalog project')
+    return clean

ft_tui/api/client_factory.py

@@ -0,0 +1,17 @@
+"""Select the online provider from secure device-session state."""
+
+from .http_client import HttpProjectProvider
+from .oauth_client import OAuthClient
+from .client_interface import ProjectProvider
+
+
+def provider_for_device(oauth_client: OAuthClient) -> ProjectProvider | None:
+    """Return no provider until this device has a usable 42TUI session."""
+    try:
+        credentials = oauth_client.credentials
+    except Exception:
+        # Missing/unavailable OS keychain support must not prevent local startup.
+        return None
+    if credentials is not None and credentials.access_token and credentials.refresh_token:
+        return HttpProjectProvider(oauth_client=oauth_client)
+    return None

ft_tui/api/client_interface.py

@@ -0,0 +1,52 @@
+"""Provider contract for the centralized 42TUI API."""
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class CursusSnapshot:
+    """Cursus data supplied by the centralized API."""
+
+    id: int
+    name: str
+    begin_at: datetime | None = None
+    end_at: datetime | None = None
+
+
+class ProjectProvider(Protocol):
+    """Authenticated catalog reader. No browser credentials enter this interface."""
+    def get_social(self) -> dict: ...
+    def get_poke_neighbours(self) -> list[dict]: ...
+    def social_action(self, draft: dict) -> dict: ...
+    def event_stream(self, stop): ...
+    def list_cursuses(self) -> list[CursusSnapshot]: ...
+    def list_campuses(self) -> list[dict]: ...
+    def get_profile(self) -> dict: ...
+    def get_cluster_map(self) -> dict: ...
+    def get_cluster_portrait(self, hostname: str) -> dict: ...
+    def get_cluster_issues(self, hostname: str, *, include_resolved: bool = False, cursor: str | None = None) -> dict: ...
+    def get_cluster_issue_options(self) -> dict: ...
+    def submit_cluster_issue(self, hostname: str, draft: dict, idempotency_key: str) -> dict: ...
+    def search_students(self, query: str, *, limit=20, exclude_ids=()) -> dict: ...
+    def list_friend_directory_page(self, campus_id: int, page: int = 1) -> dict: ...
+    def get_friend_core(self, login: str, cursus_id: int, *, refresh=False, user_id=None) -> dict: ...
+    def get_friend(self, login: str, cursus_id: int, *, refresh=False, user_id=None) -> dict: ...
+    def get_goals(self, cursus_id: int, account_id: str) -> dict: ...
+    def list_catalog_page(self, scope, **filters) -> dict: ...
+    def get_catalog_project(self, project_id: int, scope, snapshot_id=None) -> dict: ...
+    def list_branches(self, scope, track: str, cursor=None) -> dict: ...
+    def get_branch(self, scope, track: str, branch_id: str, snapshot_id=None) -> dict: ...
+    def get_account_projects(self, cursus_id: int, cursor=None) -> dict: ...
+    def get_project_activity(self, project_id: int, scope, account_id: str, *, refresh=False) -> dict: ...
+    def get_team_evaluations(self, project_id: int, team_id: int, scope, account_id: str, *, refresh=False) -> dict: ...
+    def get_project_team(self, project_id: int, scope, account_id: str) -> dict: ...
+    def change_project_team(self, project_id: int, scope, account_id: str, action: dict, idempotency_key: str) -> dict: ...
+    def get_project_registration(self, project_id: int, scope, account_id: str) -> dict: ...
+    def refresh_project_registration(self, project_id: int, scope, account_id: str) -> dict: ...
+    def register_project(self, project_id: int, scope, account_id: str, idempotency_key: str) -> dict: ...
+    def get_curriculum(self, scope) -> dict: ...
+    def get_subject_reference_sha256(self, slug: str) -> str | None: ...
+    def download_subject_pdf(self, slug: str, destination: Path) -> bool: ...

ft_tui/api/clubs_types.py

@@ -0,0 +1,106 @@
+"""Validation for the shared Clubs contract before rendering server data."""
+from uuid import UUID
+from datetime import datetime
+
+
+def timestamp(value):
+    if not isinstance(value, str):
+        raise ValueError('Invalid club timestamp')
+    parsed = datetime.fromisoformat(value.replace('Z', '+00:00'))
+    if parsed.tzinfo is None:
+        raise ValueError('Missing club timezone')
+    return value
+
+
+def club_id(value):
+    if not isinstance(value, str):
+        raise ValueError('Invalid club ID')
+    if value.startswith('campus-') and value[7:].isdigit() and int(value[7:]) > 0:
+        return value
+    UUID(value)
+    return value
+
+
+def preferences(value):
+    if not isinstance(value, dict) or type(value.get('dnd')) is not bool or not isinstance(value.get('bells'), dict):
+        raise ValueError('Invalid club preferences')
+    for key, bell in value['bells'].items():
+        club_id(key)
+        if type(bell) is not bool:
+            raise ValueError('Invalid club bell')
+    return value
+
+
+def club(value):
+    if not isinstance(value, dict):
+        raise ValueError('Invalid club')
+    club_id(value.get('id'))
+    if (type(value.get('campus_id')) is not int or value['campus_id'] < 1
+            or any(not isinstance(value.get(k), str) for k in ('name', 'description'))
+            or any(type(value.get(k)) is not bool for k in ('system', 'archived'))
+            or 'can_announce' in value and type(value['can_announce']) is not bool
+            or value.get('my_role') not in ('creator', 'delegate', 'member', None)
+            or not isinstance(value.get('members'), list) or len(value['members']) > 100
+            or not isinstance(value.get('activities'), list) or len(value['activities']) > 100
+            or not isinstance(value.get('events'), list) or len(value['events']) > 100):
+        raise ValueError('Invalid club data')
+    for member in value['members']:
+        if (not isinstance(member, dict) or not isinstance(member.get('account_id'), str)
+                or not member['account_id'].isdigit() or not isinstance(member.get('login'), str)
+                or member.get('role') not in ('creator', 'delegate', 'member')):
+            raise ValueError('Invalid club member')
+    for item in value['activities']:
+        UUID(item['id'])
+        timestamp(item.get('created_at'))
+        timestamp(item.get('expires_at'))
+        if (item.get('status') not in ('recruiting', 'ready', 'started', 'finished', 'cancelled', 'expired')
+                or any(not isinstance(item.get(k), str) for k in ('title', 'location', 'organizer_id', 'created_at', 'expires_at'))
+                or type(item.get('minimum')) is not int or type(item.get('capacity')) is not int
+                or not 1 <= item['minimum'] <= item['capacity'] <= 100
+                or any(not isinstance(item.get(k), list) or len(item[k]) > 100
+                       or any(not isinstance(i, str) or not i.isdigit() for i in item[k])
+                       for k in ('participants', 'waitlist'))
+                or len(item['participants']) > item['capacity']):
+            raise ValueError('Invalid club activity')
+    for item in value['events']:
+        event(item)
+    return value
+
+
+def event(value):
+    if (not isinstance(value, dict) or type(value.get('sequence')) is not int
+            or value.get('kind') not in ('activity', 'ready', 'started', 'cancelled', 'announcement')
+            or any(not isinstance(value.get(k), str) for k in ('actor_id', 'title', 'message', 'created_at', 'expires_at'))):
+        raise ValueError('Invalid club event')
+    for key, limit in (('actor_login', 100), ('location', 200)):
+        if key in value and (not isinstance(value[key], str) or not 1 <= len(value[key]) <= limit):
+            raise ValueError('Invalid announcement metadata')
+    if 'event_at' in value:
+        timestamp(value['event_at'])
+    timestamp(value.get('created_at'))
+    timestamp(value.get('expires_at'))
+    if value.get('activity_id') is not None:
+        UUID(value['activity_id'])
+    return value
+
+
+def overview(value):
+    preferences(value)
+    if (not isinstance(value.get('account_id'), str) or not value['account_id'].isdigit()
+            or not isinstance(value.get('clubs'), list)):
+        raise ValueError('Invalid clubs overview')
+    for item in value['clubs']:
+        club(item)
+    return value
+
+
+def poll(value):
+    preferences(value)
+    if not isinstance(value.get('notifications'), list) or len(value['notifications']) > 5:
+        raise ValueError('Invalid club notifications')
+    for item in value['notifications']:
+        club_id(item['club_id'])
+        if not isinstance(item.get('club_name'), str):
+            raise ValueError('Invalid club notification')
+        event(item['event'])
+    return value

ft_tui/api/cluster_map_types.py

@@ -0,0 +1,75 @@
+"""Validate the authenticated cluster snapshot before UI consumption."""
+from datetime import datetime
+import re
+from ft_tui.cluster_map.geometry import positions
+
+
+def _meta(value):
+    if not isinstance(value,dict) or type(value.get('stale')) is not bool:
+        raise ValueError('Invalid cluster freshness')
+    stamp = datetime.fromisoformat(value['cached_at'].replace('Z','+00:00'))
+    if stamp.tzinfo is None:
+        raise ValueError('Invalid cluster freshness')
+
+
+def cluster_portrait(value: object, hostname: str) -> dict:
+    if not isinstance(value,dict) or value.get('hostname')!=hostname or value.get('status') not in ('ready','pending','unavailable'):
+        raise ValueError('Invalid cluster portrait')
+    source=value.get('image_url');image=value.get('image_base64')
+    if source is not None and (not isinstance(source,str) or len(source)>2048):raise ValueError('Invalid cluster portrait')
+    if value['status']=='ready':
+        if not source or not isinstance(image,str) or not 0<len(image)<=699052:raise ValueError('Invalid cluster portrait')
+    elif image is not None:raise ValueError('Invalid cluster portrait')
+    _meta(value.get('meta'))
+    return value
+
+
+def cluster_map_snapshot(value: object) -> dict:
+    def fail(): raise ValueError('Invalid cluster snapshot')
+    if not isinstance(value,dict) or type(value.get('campus_id')) is not int or not isinstance(value.get('machines'),list) or len(value['machines'])>2000:
+        fail()
+    seen=set()
+    for row in value['machines']:
+        if not isinstance(row,dict):fail()
+        host=row.get('hostname')
+        if not isinstance(host,str) or not re.fullmatch(r'[a-zA-Z0-9.-]{1,253}\.42angouleme\.fr',host) or host.lower() in seen:fail()
+        seen.add(host.lower())
+        if not isinstance(row.get('status'),str) or row.get('is_locked') is not None and type(row['is_locked']) is not bool:fail()
+        for key in ('login','exam_user','lock_time'):
+            if row.get(key) is not None and (not isinstance(row[key],str) or len(row[key])>128 or any(ord(c)<32 for c in row[key])):fail()
+        person=row.get('person')
+        if person is not None and (not isinstance(person,dict) or person.get('login')!=row.get('login')):fail()
+        if person:
+            for key,limit in (('display_name',513),('image_url',2048),('user_id',16)):
+                if person.get(key) is not None and (not isinstance(person[key],str) or len(person[key])>limit):fail()
+        issues=row.get('issues')
+        if issues is not None:
+            if not isinstance(issues,dict) or issues.get('availability') not in ('available','unavailable'):fail()
+            count=issues.get('open_count')
+            if issues['availability']=='available' and (type(count) is not int or not 0<=count<=10000):fail()
+            if issues['availability']=='unavailable' and count is not None:fail()
+        if row.get('storage') is not None and (not isinstance(row['storage'],dict) or any(v is not None and not isinstance(v,str) for v in row['storage'].values())):fail()
+    try:_meta(value.get('meta'))
+    except (KeyError,TypeError,AttributeError,ValueError):fail()
+    return value
+
+
+def cluster_issue_page(value: object, hostname: str, include_resolved: bool) -> dict:
+    def fail():raise ValueError('Invalid cluster reports')
+    if not isinstance(value,dict) or value.get('hostname')!=hostname or value.get('include_resolved') is not include_resolved:fail()
+    if not isinstance(value.get('items'),list) or len(value['items'])>50:fail()
+    cursor=value.get('next_cursor')
+    if cursor is not None and (not isinstance(cursor,str) or not re.fullmatch(r'[1-9]\d{0,2}',cursor) or int(cursor)>200):fail()
+    seen=set()
+    for item in value['items']:
+        if not isinstance(item,dict) or not isinstance(item.get('id'),str) or item['id'] in seen or item.get('hostname')!=hostname:fail()
+        seen.add(item['id'])
+        if item.get('status') not in (('open','in_progress','resolved') if include_resolved else ('open','in_progress')):fail()
+        for field in ('title','description'):
+            if not isinstance(item.get(field),str) or len(item[field])>20000:fail()
+        if not isinstance(item.get('history'),list) or len(item['history'])>200:fail()
+        for entry in item['history']:
+            if not isinstance(entry,dict) or not isinstance(entry.get('content'),str) or len(entry['content'])>20000:fail()
+    try:_meta(value.get('meta'))
+    except (KeyError,TypeError,AttributeError,ValueError):fail()
+    return value