FSClient - Fellesstudentsystem GraphQL Client

A production-ready Python GraphQL client for the Fellesstudentsystem API with intelligent fragment loading, pagination support, and clean iterator-based architecture.

Features

🚀 Iterator-Only API: Memory-efficient pagination with Python's iterator protocol
🧩 Smart Fragment Management: Automatic fragment dependency resolution
📋 Schema-Based Organization: GraphQL fragments organized by schema types
⚙️ Configuration-Driven: Pydantic-based configuration with validation
🔍 Type Safety: Full type hints and comprehensive documentation
🎯 Production Ready: Robust error handling, logging, and testing
🔧 Fully Extensible: Multi-directory override system for custom fragments and operations

Extensibility

FSClient supports full customization through unified directory configuration:

# Multiple directories with override capability
config = FSClientConfig(
    api_url="https://api.example.com/graphql",
    api_key="your-api-key",
    graphql_dirs=["custom/graphql", "dir/other"],  # dir/other overrides custom/graphql which overrides built-in
    extend_builtin_queries=True  # Include built-in package queries
)

# Extend with custom operations via subclassing
class CustomFSClient(FSClient):
    def get_my_custom_operation(self, filter_obj, pagination=None):
        return self._iter_pages('myCustomOperation', filter_obj, pagination)

client = CustomFSClient(config)
filter_obj = {"param": "value"}
for page in client.get_my_custom_operation(filter_obj):
    items = page['myCustomOperation']['nodes']
    process_items(items)

Key Benefits:

Override any built-in fragment or operation
Add custom operations via explicit subclassing (better IDE support)
Priority-based loading (later directories override earlier ones)
Unified configuration with single graphql_dirs parameter

See PUBLIC_MODULE_EXTENSIBILITY.md for detailed documentation.

Quick Start

from fs_graphql_client import FSClient, FSClientConfig
from fs_graphql_client.pagination_types import PaginationParams

# Load configuration
config = FSClientConfig.from_json_file('config.json')
client = FSClient(config)

# Get all emne studieretter for organization 194
for page in client.get_emne_studieretter('194'):
    items = page['emneStudieretter']['nodes']
    print(f"Processing {len(items)} emne studieretter")

# Get terminer with year filter
for page in client.get_terminer('194', arstall=[2024, 2025]):
    items = page['terminer']['nodes']
    for termin in items:
        print(f"{termin['arstall']} {termin['betegnelse']['kode']}")

Architecture Overview

Core Components

FSClient: Main GraphQL client with operation methods
GraphQLClient: Base client with fragment loading and schema validation
FSClientConfig: Pydantic configuration model
PaginationParams: Type-safe pagination parameter handling

Iterator-Only Design

All operations return iterators that yield complete page responses:

# Single page
pages = client.get_emne_studieretter('194')
first_page = next(pages)

# All pages
for page in client.get_emne_studieretter('194'):
    process_page(page)

# With pagination parameters
pagination = PaginationParams.forward(100)
for page in client.get_emne_studieretter('194', pagination=pagination):
    process_page(page)

Available Operations

`get_emne_studieretter(eier_organisasjonskode, pagination=None, **filter_args)`

Get course enrollments for an organization.

Parameters:

eier_organisasjonskode (str): Organization code (e.g., '194' for NTNU)
pagination (PaginationParams, optional): Pagination parameters
**filter_args: Additional filters using GraphQL camelCase names:
- terminer: List of term IDs or single term ID
- opptakKanPubliseres: Boolean for publishable admissions

Example:

# All enrollments for Spring 2025
spring_2025_id = "MTE2OjE5NCwyMDI1LFbDhVI"
for page in client.get_emne_studieretter('194', terminer=spring_2025_id):
    enrollments = page['emneStudieretter']['nodes']
    for enrollment in enrollments:
        print(f"Student: {enrollment['student']['studentnummer']}")
        print(f"Course: {enrollment['emne']['kode']}")

`get_terminer(eier_organisasjonskode, pagination=None, **filter_args)`

Get terms for an organization.

Parameters:

eier_organisasjonskode (str): Organization code
pagination (PaginationParams, optional): Pagination parameters
**filter_args: Additional filters:
- arstall: List of years (e.g., [2024, 2025])
- terminbetegnelser: List of term designation IDs

Example:

# Terms for 2024-2025
for page in client.get_terminer('194', arstall=[2024, 2025]):
    terms = page['terminer']['nodes']
    for term in terms:
        print(f"{term['arstall']} {term['betegnelse']['kode']}")
        # Output: 2024 HØST, 2025 VÅR, etc.

`get_program_studieretter(eier_organisasjonskode, pagination=None, **filter_args)`

Get program enrollments for an organization.

Parameters:

eier_organisasjonskode (str): Organization code (e.g., '194' for NTNU)
pagination (PaginationParams, optional): Pagination parameters
**filter_args: Additional filters using GraphQL camelCase names. Available filters depend on the GraphQL schema for QueryProgramStudieretterFilterInput. Consult the API documentation or GraphQL schema for specific filter options.

Example:

# All program enrollments
for page in client.get_program_studieretter('194'):
    enrollments = page['programStudieretter']['nodes']
    for enrollment in enrollments:
        print(f"Student: {enrollment['student']['studentnummer']}")
        print(f"Program: {enrollment['studieprogram']['kode']}")

# With pagination
pagination = PaginationParams.forward(100)
for page in client.get_program_studieretter('194', pagination=pagination):
    process_program_enrollments(page)

Configuration

JSON Configuration File

{
  "fs_graphql": {
    "api_url": "https://api.example.com/graphql/",
    "api_key": "your-api-key",
    "connect_timeout_seconds": 5.0,
    "read_timeout_seconds": 30.0,
    "graphql_dirs": ["fs_graphql_client/queries"]
  }
}

Configuration Options

api_url (required): GraphQL API endpoint URL
api_key (required): API authentication key
connect_timeout_seconds (5.0): Connection timeout in seconds
read_timeout_seconds (30.0): Read timeout in seconds
graphql_dirs ([]): List of directories for GraphQL files

GraphQL File Organization

The client uses a schema-based organization for GraphQL files:

fs_graphql_client/queries/
├── emneStudieretter.graphql          # EmneStudieretter query operation
├── terminer.graphql                  # Terminer query operation
├── Emne.fragments.graphql            # Emne schema type fragments
├── EmneStudierett.fragments.graphql  # EmneStudierett schema type fragments
├── PersonProfil.fragments.graphql    # PersonProfil schema type fragments
├── StudentVedLarested.fragments.graphql # Student schema type fragments
├── Termin.fragments.graphql          # Termin schema type fragments
└── Shared.fragments.graphql          # Utility fragments (PageInfo)

Fragment Architecture

Fragments are organized by GraphQL schema types for better maintainability:

# Termin.fragments.graphql
# Fragments for Termin schema type

fragment TerminInfo on Termin {
  id
  betegnelse { kode, navnAlleSprak { nb, nn, en } }
  arstall
}

fragment TerminDetails on Termin {
  id
  betegnelse { kode, navnAlleSprak { nb, nn, en } }
  arstall
  oppdateringssperrer { id, undervisningsaktiviteter }
}

Pagination

PaginationParams

Type-safe pagination parameter handling:

from fs_graphql_client.pagination_types import PaginationParams

# Forward pagination
pagination = PaginationParams.forward(page_size=100)

# Cursor-based pagination
pagination = PaginationParams.forward(page_size=50, after="cursor_string")

# Custom pagination
pagination = PaginationParams(
    first=100,
    after="cursor_string"
)

Page Response Structure

All operations return standardized page responses:

{
  "emneStudieretter": {  # or "terminer"
    "totalCount": 1500,
    "nodes": [...],      # Array of data items
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "...",
      "endCursor": "..."
    }
  }
}

Error Handling

The client provides comprehensive error handling:

from gql.transport.exceptions import TransportError

try:
    for page in client.get_emne_studieretter('194'):
        process_page(page)
except TransportError as e:
    print(f"GraphQL transport error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Development

Adding New Operations

Create GraphQL query file: new_operation.graphql
Add method to FSClient: Follow the iterator pattern
Create/update fragments: Organize by schema type
Add tests: Validate the new operation

Example new operation:

def get_new_operation(
    self,
    eier_organisasjonskode: str,
    pagination: Optional[PaginationParams] = None,
    **filter_args
) -> Iterator[Dict[str, Any]]:
    """Get new operation data."""
    filter_obj = self.build_filter(
        mandatory_fields={"eierOrganisasjonskode": eier_organisasjonskode},
        **filter_args
    )
    
    return self._iter_pages(
        operation_name="newOperation",
        filter_obj=filter_obj,
        pagination=pagination
    )

Testing

# Basic operation test
from fs_graphql_client import FSClient, FSClientConfig

config = FSClientConfig.from_json_file('config.json')
client = FSClient(config)

# Test terminer
for page in client.get_terminer('194', arstall=[2025]):
    assert len(page['terminer']['nodes']) > 0
    print("✅ Terminer operation works")

# Test emne studieretter  
for page in client.get_emne_studieretter('194'):
    assert len(page['emneStudieretter']['nodes']) > 0
    print("✅ EmneStudieretter operation works")
    break  # Test just first page

Package Structure

fsclient/
├── __init__.py                       # Package exports
├── base_config.py                    # Base configuration class
├── fs_client.py                      # Main FSClient class
├── fs_client_config.py               # FSClient configuration
├── pagination_types.py               # Pagination utilities
├── graphql_client.py                 # Base GraphQL client
├── requirements.txt                  # Dependencies
└── queries/                          # GraphQL files
    ├── emneStudieretter.graphql      # Operations
    ├── terminer.graphql
    ├── Emne.fragments.graphql        # Schema-based fragments
    ├── EmneStudierett.fragments.graphql
    ├── PersonProfil.fragments.graphql
    ├── StudentVedLarested.fragments.graphql
    ├── Termin.fragments.graphql
    └── Shared.fragments.graphql

Dependencies

gql: GraphQL client library with transport and validation
pydantic: Data validation and configuration management
requests: HTTP transport for GraphQL operations

License

This project is licensed under the MIT License.

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request

For questions or issues, please create an issue in the repository.

it-dataflyt/fsgraphql

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages