### Install autokattis Package

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Install the autokattis package using pip. This is the initial setup step.

```sh
pip install autokattis
```

--------------------------------

### Installation

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Install the autokattis package using pip.

```APIDOC
## Installation

Simply install it as a Python package.

```sh
$ pip install autokattis
```
```

--------------------------------

### Get OpenKattis Help Information

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Use this to access the docstrings and get more information about the OpenKattis class and its return values. This is useful for understanding the structure of the data returned by the library.

```python
from autokattis import OpenKattis
help(OpenKattis)
```

--------------------------------

### Get Kattis Problem Recommendations

Source: https://context7.com/russelldash332/autokattis/llms.txt

Get personalized problem suggestions based on your solving history.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

suggestions = kt.suggest()
```

--------------------------------

### Get Problem Suggestions and Metadata (OpenKattis)

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Fetch personalized problem suggestions, user achievements, and lists of problem authors and sources.

```python
kt.suggest()
```

```python
kt.achievements()
```

```python
kt.problem_authors()
```

```python
kt.problem_sources()
```

--------------------------------

### Fetch Kattis Problem Details

Source: https://context7.com/russelldash332/autokattis/llms.txt

Get detailed information about specific problems, including metadata, statistics, and submissions. Optionally download sample test files. Can fetch details for multiple problems at once.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

# Fetch single problem details
info = kt.problem('2048')
# [{'id': '2048', 'text': 'Problem statement...', 'cpu': '1 second',
#   'memory': '1024 MB', 'difficulty': 2.3, 'category': 'Easy',
#   'author': 'Author Name', 'source': 'Contest Name',
#   'statistics': {...}, 'submissions': [...], 'breakpoints': [...]}]

# Fetch multiple problems at once
problems = kt.problem(['2048', 'hello', 'aplusb'])
problems = kt.problem({'2048', 'hello', 'aplusb'})  # sets work too

# Download sample test files
info = kt.problem('2048', download_files=True)
# info[0]['files'] = {'2048.zip': {'sample.in': '2 2\n4 4...', 'sample.ans': '4\n'}}

# Access your submission history for this problem
for submission in info[0]['submissions']:
    print(f"{submission['status']} - {submission['runtime']} - {submission['language']}")
    # Accepted - 0.01 s - Python 3
```

--------------------------------

### Get Global Top 100 Users Ranklist

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves the global top 100 users ranklist. The data can be converted to a DataFrame for analysis, such as grouping users by country and counting them.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

top_users = kt.user_ranklist()
# [{'rank': 1, 'name': 'Top Coder', 'username': 'topcoder', 'points': 99999.9,
#   'country_code': 'USA', 'country': 'United States',
#   'affiliation_code': 'mit.edu', 'affiliation': 'MIT'}, ...]

# Group top users by country
df = kt.user_ranklist().to_df()
print(df.groupby('country').size().sort_values(ascending=False).head(10))
```

--------------------------------

### Get Challenge Ladder Rankings

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves the top 100 users in the challenge ladder, which focuses on optimization problems. The results can be converted to a DataFrame for further examination of user rankings and scores.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

challenge_top = kt.challenge_ranklist()
# [{'rank': 1, 'name': 'Optimizer', 'username': 'optimizer', 'score': 99999.9,
#   'country_code': 'USA', 'country': 'United States',
#   'affiliation_code': 'mit.edu', 'affiliation': 'MIT'}, ...]

df = kt.challenge_ranklist().to_df()
print(df[['rank', 'name', 'score', 'country']].head(10))
```

--------------------------------

### Get Personal Ranklist

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves the ranklist showing users near your current position. The results can be converted to a DataFrame to easily find your specific rank by filtering on your username.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

nearby = kt.ranklist()
# [{'rank': 103, 'name': 'Jack', 'points': 12345.6, 'country': 'United States',
#   'affiliation': 'MIT', 'username': 'jackdoe', 'country_code': 'USA',
#   'affiliation_code': 'mit.edu'}, ...]

# Find your position
df = kt.ranklist().to_df()
my_rank = df[df['username'] == kt.get_username()]
```

--------------------------------

### Get Country Rankings

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves the top 100 countries by rank or the top 50 users from a specific country. Country can be specified by name or country code. The results can be converted to a DataFrame for detailed inspection.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

# Top 100 countries
countries = kt.country_ranklist()
# [{'rank': 1, 'country': 'United States', 'country_code': 'USA',
#   'users': 12345, 'affiliations': 2345, 'points': 9999.9}, ...]

# Top 50 users in a specific country (by name or code)
sg_users = kt.country_ranklist('Singapore')
sg_users = kt.country_ranklist('SGP')  # using country code

df = kt.country_ranklist('SGP').to_df()
print(df[['rank', 'name', 'points', 'affiliation']].head(10))
```

--------------------------------

### Initialize OpenKattis Login

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Construct an OpenKattis object for authentication. Provide username and password as strings, or just username to be prompted.

```python
from autokattis import OpenKattis
kt = OpenKattis('username', 'password')
```

```python
kt = OpenKattis('username')
```

--------------------------------

### Initialize NUSKattis Login

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Construct a NUSKattis object for authentication. Provide username and password as strings, or just username to be prompted.

```python
from autokattis import NUSKattis
kt = NUSKattis('username', 'password')
```

```python
kt = NUSKattis('username')
```

--------------------------------

### Initialize NUSKattis Session

Source: https://context7.com/russelldash332/autokattis/llms.txt

Creates a session for the National University of Singapore Kattis instance. Supports both direct password entry and interactive password prompts.

```python
from autokattis import NUSKattis

kt = NUSKattis('your_nus_email', 'your_password')

# Or with interactive password prompt
kt = NUSKattis('your_nus_email')
# Enter password: ********
```

--------------------------------

### OpenKattis.suggest() - Problem Recommendations

Source: https://context7.com/russelldash332/autokattis/llms.txt

Provides personalized problem recommendations based on the user's past solving history.

```APIDOC
## OpenKattis.suggest() - Problem Recommendations

Get personalized problem suggestions based on your solving history.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

suggestions = kt.suggest()
```
```

--------------------------------

### NUSKattis - Course-specific

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Interact with NUSKattis for course-specific data.

```APIDOC
## NUSKattis - Course-specific

```py
kt.courses()                                    # current and recently ended courses
kt.offerings('CS3233')                          # course offerings
kt.assignments('CS3233_S2_AY2223')              # offering assignments but course ID not provided
kt.assignments('CS3233_S2_AY2223', 'CS3233')    # offering assignments
```
```

--------------------------------

### NUSKattis - Login and Session Management

Source: https://context7.com/russelldash332/autokattis/llms.txt

Initializes a NUSKattis session for the National University of Singapore Kattis instance.

```APIDOC
## NUSKattis()

### Description
Create a NUSKattis session for the National University of Singapore Kattis instance.

### Method
POST

### Endpoint
/login

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **your_nus_email** (string) - Required - Your NUS email address.
- **your_password** (string) - Optional - Your password. If not provided, an interactive prompt will be used.

### Request Example
```python
from autokattis import NUSKattis

# With password provided
kt = NUSKattis('your_nus_email', 'your_password')

# With interactive password prompt
kt = NUSKattis('your_nus_email')
```

### Response
#### Success Response (200)
- **session** (object) - An active session object for interacting with NUS Kattis.

#### Response Example
(No specific JSON response example provided, but an active session object is returned.)
```

--------------------------------

### Login and Session Management

Source: https://context7.com/russelldash332/autokattis/llms.txt

Establishes a session with the Kattis platform using provided username and password. The password can be omitted for an interactive prompt.

```APIDOC
## Login and Session Management

Create an OpenKattis session by providing your username and password. The password can be omitted to trigger an interactive prompt.

```python
from autokattis import OpenKattis

# Login with username and password
kt = OpenKattis('your_username', 'your_password')

# Or login with interactive password prompt
kt = OpenKattis('your_username')
# Enter password: ********

# Backwards compatible alias
from autokattis import Kattis
kt = Kattis('your_username', 'your_password')
```
```

--------------------------------

### Get Affiliation Rankings

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves the top 100 affiliations (universities/organizations) or the top 50 users from a specific affiliation. Affiliation can be specified by name or domain. Results can be converted to a DataFrame for detailed analysis.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

# Top 100 affiliations
affiliations = kt.affiliation_ranklist()
# [{'rank': 1, 'affiliation': 'MIT', 'affiliation_code': 'mit.edu',
#   'country': 'United States', 'country_code': 'USA',
#   'subdivision': None, 'users': 5000, 'points': 99999.9}, ...]

# Top 50 users from specific affiliation
nus_users = kt.affiliation_ranklist('National University of Singapore')
nus_users = kt.affiliation_ranklist('nus.edu.sg')  # using domain

df = kt.affiliation_ranklist('nus.edu.sg').to_df()
print(df[['rank', 'name', 'points']].head(10))
```

--------------------------------

### Create OpenKattis Session

Source: https://context7.com/russelldash332/autokattis/llms.txt

Create an OpenKattis session by providing your username and password. The password can be omitted to trigger an interactive prompt. This is a backwards compatible alias.

```python
from autokattis import OpenKattis

# Login with username and password
kt = OpenKattis('your_username', 'your_password')

# Or login with interactive password prompt
kt = OpenKattis('your_username')
# Enter password: ********

# Backwards compatible alias
from autokattis import Kattis
kt = Kattis('your_username', 'your_password')
```

--------------------------------

### OpenKattis.problem() - Fetch Problem Details

Source: https://context7.com/russelldash332/autokattis/llms.txt

Fetches detailed information for one or more specific problems, including metadata, statistics, and user submissions. Optionally downloads sample test files.

```APIDOC
## OpenKattis.problem() - Fetch Problem Details

Get detailed information about specific problems including metadata, statistics, your submissions, and optionally download sample test files.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

# Fetch single problem details
info = kt.problem('2048')
# [{'id': '2048', 'text': 'Problem statement...', 'cpu': '1 second',
#   'memory': '1024 MB', 'difficulty': 2.3, 'category': 'Easy',
#   'author': 'Author Name', 'source': 'Contest Name',
#   'statistics': {...}, 'submissions': [...], 'breakpoints': [...]}]

# Fetch multiple problems at once
problems = kt.problem(['2048', 'hello', 'aplusb'])
problems = kt.problem({'2048', 'hello', 'aplusb'})  # sets work too

# Download sample test files
info = kt.problem('2048', download_files=True)
# info[0]['files'] = {'2048.zip': {'sample.in': '2 2\n4 4...', 'sample.ans': '4\n'}}

# Access your submission history for this problem
for submission in info[0]['submissions']:
    print(f"{submission['status']} - {submission['runtime']} - {submission['language']}")
    # Accepted - 0.01 s - Python 3
```
```

--------------------------------

### Fetch Course Information (NUSKattis)

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Retrieve information about current and past courses, their offerings, and assignments. Requires course and offering IDs for assignments.

```python
kt.courses()
```

```python
kt.offerings('CS3233')
```

```python
kt.assignments('CS3233_S2_AY2223')
```

```python
kt.assignments('CS3233_S2_AY2223', 'CS3233')
```

--------------------------------

### Login to OpenKattis

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Construct an OpenKattis object with your username and password.

```APIDOC
## Login to OpenKattis

Construct an `OpenKattis` object that takes in the username and the password.

```py
from autokattis import OpenKattis
kt = OpenKattis('username', 'password')
kt = OpenKattis('username') # which will then prompt you for the password
```

where `'username'` is your Kattis username/email and `'password'` is your Kattis account password. **Both should be provided as Python strings.**
```

--------------------------------

### Create Difficulty Mapping

Source: https://context7.com/russelldash332/autokattis/llms.txt

Fetches all problems from OpenKattis and creates a dictionary mapping problem IDs to their difficulty levels. Ensure you have valid Kattis credentials.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

# Create difficulty mapping from Open Kattis
df = kt.problems().to_df()
diff_map = dict(zip(df.id, df.difficulty))
```

--------------------------------

### Fetch Ranklists (OpenKattis)

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Retrieve various ranklists, including users around the current user, general and challenge ladder top users, and country/affiliation rankings.

```python
kt.ranklist()
```

```python
kt.user_ranklist()
```

```python
kt.challenge_ranklist()
```

```python
kt.country_ranklist()
```

```python
kt.country_ranklist('Singapore')
```

```python
kt.country_ranklist('SGP')
```

```python
kt.affiliation_ranklist()
```

```python
kt.affiliation_ranklist(affiliation='National University of Singapore')
```

```python
kt.affiliation_ranklist(affiliation='nus.edu.sg')
```

--------------------------------

### OpenKattis - Problem-specific

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Interact with OpenKattis for problem-specific data and actions.

```APIDOC
## OpenKattis - Problem-specific

> Due to backwards compatibility, you can still use `Kattis` as a shorthand form of `OpenKattis`.

```py
kt.problems()                               # problems you have solved so far
kt.problems(show_partial=False)             # exclude partial submissions
kt.problems(low_detail_mode=False)          # include more data for each problem
kt.problems(*[True]*4)                      # show literally all problems on Open Kattis

kt.plot_problems()                          # plot the points distribution
kt.plot_problems(filepath='plot.png')       # save to a filepath
kt.plot_problems(show_partial=False)        # plot fully solved submissions

kt.problem('2048')                          # fetch info about a problem
kt.problem(['2048', 'abinitio', 'dasort'])  # fetch multiple in one
kt.problem({'2048', 'abinitio', 'dasort'})  # tuples or sets also allowed
kt.problem('2048', download_files=True)     # download files too

kt.stats()                                  # your best submission for each problem
kt.stats('Java')                            # all your Java submissions
kt.stats(('Python3', 'Cpp'))                # multiple languages

kt.suggest()                                # what's the next problem for me?
kt.achievements()                           # do I have any?
kt.problem_authors()                        # list down all problem authors
kt.problem_sources()                        # list down all problem sources
```
```

--------------------------------

### NUSKattis - Problem-specific

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Interact with NUSKattis for problem-specific data.

```APIDOC
## NUSKattis - Problem-specific

```py
kt.problems()                               # problems you have solved so far, only supports low detail mode
kt.problems(show_solved=False)              # show literally all problems on NUS Kattis

kt.problem('2048')                          # fetch info about a problem
kt.problem(['2048', 'abinitio', 'dasort'])  # fetch multiple in one
kt.problem({'2048', 'abinitio', 'dasort'})  # tuples or sets also allowed
kt.problem('2048', download_files=True)     # download files too

kt.stats()                                  # your best submission for each problem
kt.stats('Java')                            # all your Java submissions
kt.stats(('Python3', 'Cpp'))                # multiple languages
```
```

--------------------------------

### Login to NUSKattis

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Construct a NUSKattis object with your username and password.

```APIDOC
## Login to NUSKattis

Similarly if you want to login to NUS Kattis.

```py
from autokattis import NUSKattis
kt = NUSKattis('username', 'password')
kt = NUSKattis('username')
```
```

--------------------------------

### Run NUSKattis Tests

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Execute the test suite for the NUSKattis functionality. This command is run from the terminal.

```shell
python test/nuskattis.py
```

--------------------------------

### NUSKattis.offerings() - List Course Offerings

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves all offerings (semesters) for a specific NUS course.

```APIDOC
## NUSKattis.offerings()

### Description
Get all offerings (semesters) for a specific NUS course.

### Method
GET

### Endpoint
/courses/{course_id}/offerings

### Parameters
#### Path Parameters
- **course_id** (string) - Required - The ID of the course for which to fetch offerings.

### Request Example
```python
from autokattis import NUSKattis

kt = NUSKattis('username', 'password')

offerings = kt.offerings('CS2040')
```

### Response
#### Success Response (200)
- **name** (string) - The name of the offering (e.g., semester and academic year).
- **status** (string) - The status of the offering (e.g., 'teaching', 'registered').
- **end_date** (string) - The end date of the offering.
- **link** (string) - A URL to the specific offering on NUS Kattis.

#### Response Example
```json
[
  {
    "name": "CS2040_S1_AY2425",
    "status": "teaching",
    "end_date": "2024-12-08",
    "link": "https://nus.kattis.com/courses/CS2040/CS2040_S1_AY2425"
  },
  {
    "name": "CS2040_S2_AY2324",
    "status": "registered",
    "end_date": "2024-05-06",
    "link": "https://nus.kattis.com/courses/CS2040/CS2040_S2_AY2324"
  }
]
```
```

--------------------------------

### Run OpenKattis Tests

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Execute the test suite for the OpenKattis functionality. This command is run from the terminal.

```shell
python test/openkattis.py
```

--------------------------------

### Fetch Problem Information (OpenKattis)

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Retrieve detailed information about specific problems. Supports fetching single or multiple problems by ID, and can optionally download associated files.

```python
kt.problem('2048')
```

```python
kt.problem(['2048', 'abinitio', 'dasort'])
```

```python
kt.problem({'2048', 'abinitio', 'dasort'})
```

```python
kt.problem('2048', download_files=True)
```

--------------------------------

### Group Top Users by Country with OpenKattis

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

This snippet groups and counts the top users by their country using data from OpenKattis. It requires initializing OpenKattis and fetching user ranklist data.

```python
okt = OpenKattis(...)
okt.user_ranklist().to_df().groupby('country').size()
```

--------------------------------

### NUSKattis.courses() - List Available Courses

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves a list of current and recently ended NUS Kattis courses.

```APIDOC
## NUSKattis.courses()

### Description
Get current and recently ended NUS Kattis courses.

### Method
GET

### Endpoint
/courses

### Parameters
None

### Request Example
```python
from autokattis import NUSKattis

kt = NUSKattis('username', 'password')

courses = kt.courses()
```

### Response
#### Success Response (200)
- **name** (string) - The name of the course.
- **url** (string) - The URL to the course on NUS Kattis.
- **course_id** (string) - The unique identifier of the course.

#### Response Example
```json
[
  {
    "name": "Data Structures and Algorithms - CS2040",
    "url": "https://nus.kattis.com/courses/CS2040",
    "course_id": "CS2040"
  },
  {
    "name": "Competitive Programming - CS3233",
    "url": "https://nus.kattis.com/courses/CS3233",
    "course_id": "CS3233"
  }
]
```
```

--------------------------------

### Fetch Solved Problems (NUSKattis)

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Retrieve a list of problems solved by the user on NUSKattis. Note that this only supports low detail mode and has an option to show all problems.

```python
kt.problems()
```

```python
kt.problems(show_solved=False)
```

--------------------------------

### OpenKattis.problem_sources() - List Problem Sources

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves a list of all problem sources (contests, competitions) on Kattis.

```APIDOC
## OpenKattis.problem_sources()

### Description
Get a list of all problem sources (contests, competitions).

### Method
GET

### Endpoint
/problem_sources

### Parameters
None

### Request Example
```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')
sources = kt.problem_sources()
```

### Response
#### Success Response (200)
- **name** (string) - The name of the problem source.
- **problems** (integer) - The number of problems from this source.
- **num_solved** (integer) - The number of problems solved from this source.
- **avg_difficulty** (float) - The average difficulty of problems from this source.
- **avg_category** (string) - The average category of problems from this source.
- **link** (string) - A URL to the problem source on OpenKattis.

#### Response Example
```json
[
  {
    "name": "ICPC World Finals 2023",
    "problems": 12,
    "num_solved": 8,
    "avg_difficulty": 7.5,
    "avg_category": "Hard",
    "link": "https://open.kattis.com/problem-sources/ICPC%20World%20Finals%202023"
  }
]
```
```

--------------------------------

### Fetch Solved Problems (OpenKattis)

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Retrieve a list of problems solved by the user on OpenKattis. Options include excluding partial submissions or including more detailed data.

```python
kt.problems()
```

```python
kt.problems(show_partial=False)
```

```python
kt.problems(low_detail_mode=False)
```

```python
kt.problems(*[True]*4)
```

--------------------------------

### List OpenKattis Problem Sources

Source: https://context7.com/russelldash332/autokattis/llms.txt

Fetches a list of all problem sources (contests, competitions) from OpenKattis. The results can be converted to a DataFrame to identify sources with the most problems or highest average difficulty.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

sources = kt.problem_sources()
# [{'name': 'ICPC World Finals 2023', 'problems': 12, 'num_solved': 8,
#   'avg_difficulty': 7.5, 'avg_category': 'Hard',
#   'link': 'https://open.kattis.com/problem-sources/ICPC%20World%20Finals%202023'}, ...]

df = kt.problem_sources().to_df()
print(df.nlargest(10, 'problems')[['name', 'problems', 'avg_difficulty']])
```

--------------------------------

### NUSKattis.assignments() - List Course Assignments

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves all assignments for a specific course offering, including their associated problem lists.

```APIDOC
## NUSKattis.assignments()

### Description
Get all assignments for a specific course offering with problem lists.

### Method
GET

### Endpoint
/courses/{course_id}/offerings/{offering_id}/assignments

### Parameters
#### Path Parameters
- **course_id** (string) - Required - The ID of the course.
- **offering_id** (string) - Required - The ID of the course offering.

### Request Example
```python
from autokattis import NUSKattis

kt = NUSKattis('username', 'password')

# With explicit course ID and offering ID
assignments = kt.assignments('CS2040_S1_AY2425', 'CS2040')
```

### Response
#### Success Response (200)
- **name** (string) - The name of the assignment.
- **problems** (array) - A list of problems included in the assignment.

#### Response Example
```json
[
  {
    "name": "Assignment 1",
    "problems": ["problem1_id", "problem2_id"]
  }
]
```
```

--------------------------------

### Map Problem ID to Difficulty with OpenKattis

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Use this snippet to create a mapping between problem IDs and their difficulties from the OpenKattis platform. Requires the OpenKattis class to be initialized.

```python
okt = OpenKattis(...)
df = okt.problems().to_df()
diff_map = dict(zip(df.id, df.difficulty))
```

--------------------------------

### OpenKattis.ranklist() - Personal Ranklist

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves the personal ranklist, showing users near your current position. The data can be converted to a DataFrame for further analysis.

```APIDOC
## OpenKattis.ranklist()

### Description
Get the ranklist showing users near your current position.

### Method
GET

### Endpoint
/ranklist

### Parameters
None

### Request Example
```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

nearby = kt.ranklist()
```

### Response
#### Success Response (200)
- **ranklist** (list) - A list of user rank objects, each containing rank, name, points, country, affiliation, and username.

#### Response Example
```json
[
  {
    "rank": 103,
    "name": "Jack",
    "points": 12345.6,
    "country": "United States",
    "affiliation": "MIT",
    "username": "jackdoe",
    "country_code": "USA",
    "affiliation_code": "mit.edu"
  }
]
```

### DataFrame Conversion
```python
# Find your position
df = kt.ranklist().to_df()
my_rank = df[df['username'] == kt.get_username()]
```
```

--------------------------------

### OpenKattis.achievements() - User Achievements

Source: https://context7.com/russelldash332/autokattis/llms.txt

Lists all user achievements on Kattis, such as fastest solution or shortest code records. It can also be converted to a DataFrame for analysis.

```APIDOC
## OpenKattis.achievements()

### Description
List all your Kattis achievements such as fastest solution or shortest code records.

### Method
GET

### Endpoint
/achievements

### Parameters
None

### Request Example
```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')
achievements = kt.achievements()
```

### Response
#### Success Response (200)
- **achievements** (list) - A list of achievement objects, each containing details like name, id, runtime, length, achievement type, difficulty, category, and link.

#### Response Example
```json
[
  {
    "name": "Hello World!",
    "id": "hello",
    "runtime": 0.01,
    "length": 10,
    "achievement": "Fastest Solution, Within 100% of shortest",
    "difficulty": 1.2,
    "category": "Easy",
    "link": "https://open.kattis.com/problems/hello"
  }
]
```

### DataFrame Conversion
```python
# Count achievements by type
df = kt.achievements().to_df()
print(df['achievement'].value_counts())
```
```

--------------------------------

### Fetch Submission Statistics (OpenKattis)

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Retrieve submission statistics, either the best submission for each problem or all submissions for specified programming languages.

```python
kt.stats()
```

```python
kt.stats('Java')
```

```python
kt.stats(('Python3', 'Cpp'))
```

--------------------------------

### List NUS Kattis Course Offerings

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves all offerings (semesters) for a specific NUS Kattis course. Results can be converted to a DataFrame to filter by status or end date.

```python
from autokattis import NUSKattis

kt = NUSKattis('username', 'password')

offerings = kt.offerings('CS2040')
# [{'name': 'CS2040_S1_AY2425', 'status': 'teaching', 'end_date': '2024-12-08',
#   'link': 'https://nus.kattis.com/courses/CS2040/CS2040_S1_AY2425'},
#  {'name': 'CS2040_S2_AY2324', 'status': 'registered', 'end_date': '2024-05-06',
#   'link': 'https://nus.kattis.com/courses/CS2040/CS2040_S2_AY2324'}]

df = kt.offerings('CS3233').to_df()
current = df[df['status'] == 'teaching']
```

--------------------------------

### OpenKattis.problems() - Fetch Problem Lists

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves lists of Kattis problems, with options to filter by solved status, detail level, and problem visibility (tried/untried). Results can be converted to a pandas DataFrame.

```APIDOC
## OpenKattis.problems() - Fetch Problem Lists

Retrieve the list of Kattis problems you have attempted or all available problems. Use `low_detail_mode=True` for faster results with minimal data, or `False` for comprehensive problem metadata.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

# Get only solved problems (fast, minimal data)
solved = kt.problems()
# [{'name': 'Hello World!', 'id': 'hello', 'link': 'https://open.kattis.com/problems/hello'}, ...]

# Get solved problems with full details
solved_detailed = kt.problems(low_detail_mode=False)
# [{'name': 'Hello World!', 'id': 'hello', 'fastest': 0.0, 'shortest': 5,
#   'total': 12345, 'acc': 9876, 'difficulty': 1.2, 'category': 'Easy',
#   'link': 'https://open.kattis.com/problems/hello'}, ...]

# Get all problems including untried ones
all_problems = kt.problems(show_solved=True, show_partial=True, show_tried=True, show_untried=True)

# Exclude partial solutions
fully_solved = kt.problems(show_partial=False)

# Convert to pandas DataFrame
df = kt.problems().to_df()
print(df[['id', 'name', 'difficulty']].head())
```
```

--------------------------------

### OpenKattis - Ranklist

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Retrieve ranklist information from OpenKattis.

```APIDOC
## OpenKattis - Ranklist

```py
kt.ranklist()                                                           # people around you

kt.user_ranklist()                                                      # top 100 users in general ladder
kt.challenge_ranklist()                                                 # top 100 users in challenge ladder

kt.country_ranklist()                                                   # top 100 countries
kt.country_ranklist('Singapore')                                        # specific country
kt.country_ranklist('SGP')                                              # use country code instead

kt.affiliation_ranklist()                                               # top 100 affiliations
kt.affiliation_ranklist(affiliation='National University of Singapore') # specific affiliation
kt.affiliation_ranklist(affiliation='nus.edu.sg')                       # use affiliation domain instead
```
```

--------------------------------

### OpenKattis.country_ranklist() - Country Rankings

Source: https://context7.com/russelldash332/autokattis/llms.txt

Fetches the top 100 countries by rank or the top 50 users from a specific country. Country can be specified by name or code.

```APIDOC
## OpenKattis.country_ranklist()

### Description
Get top 100 countries or the top 50 users from a specific country.

### Method
GET

### Endpoint
/ranklist/countries

### Parameters
#### Path Parameters
- **country** (string) - Optional - The name or country code of the country to retrieve user rankings for. If omitted, returns top 100 countries.

### Request Example
```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

# Top 100 countries
countries = kt.country_ranklist()

# Top 50 users in a specific country (by name or code)
sg_users = kt.country_ranklist('Singapore')
sg_users = kt.country_ranklist('SGP')  # using country code
```

### Response
#### Success Response (200)
- **countries** (list) - If no country is specified, a list of country rank objects including rank, country name, country code, number of users, affiliations, and points.
- **users** (list) - If a country is specified, a list of user rank objects for the top 50 users from that country, including rank, name, points, and affiliation.

#### Response Example (Top Countries)
```json
[
  {
    "rank": 1,
    "country": "United States",
    "country_code": "USA",
    "users": 12345,
    "affiliations": 2345,
    "points": 9999.9
  }
]
```

#### Response Example (Top Users in Country)
```json
[
  {
    "rank": 1,
    "name": "User One",
    "points": 1500.0,
    "affiliation": "Example University",
    "username": "user1",
    "country_code": "SGP",
    "country": "Singapore",
    "affiliation_code": "example.edu"
  }
]
```

### DataFrame Conversion
```python
df = kt.country_ranklist('SGP').to_df()
print(df[['rank', 'name', 'points', 'affiliation']].head(10))
```
```

--------------------------------

### NUSKattis.problem() - Fetch NUS Problem Details

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves detailed information about a specific NUS Kattis problem, including statistics, submissions, and course offering associations.

```APIDOC
## NUSKattis.problem()

### Description
Get detailed information about NUS Kattis problems, including course offering associations.

### Method
GET

### Endpoint
/problems/{problem_id}

### Parameters
#### Path Parameters
- **problem_id** (string) - Required - The ID of the problem to fetch.

#### Query Parameters
- **download_files** (boolean) - Optional - If True, downloads sample files associated with the problem.

### Request Example
```python
from autokattis import NUSKattis

kt = NUSKattis('username', 'password')

# Fetch a single problem
info = kt.problem('magicsequence')

# Fetch a single problem with sample files
info = kt.problem('magicsequence', download_files=True)

# Fetch multiple problems
problems = kt.problem(['magicsequence', 'hello', 'zbrka'])
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the problem.
- **text** (string) - The problem statement.
- **cpu** (string) - The CPU time limit.
- **memory** (string) - The memory limit.
- **author** (string) - The author of the problem.
- **source** (string) - The source (e.g., course) of the problem.
- **statistics** (object) - Statistics related to the problem.
- **submissions** (array) - A list of submissions for the problem.
- **offerings** (array) - A list of course offerings associated with the problem.

#### Response Example
```json
[
  {
    "id": "magicsequence",
    "text": "Problem statement...",
    "cpu": "2 seconds",
    "memory": "1024 MB",
    "author": "Author",
    "source": "CS2040",
    "statistics": {},
    "submissions": [],
    "offerings": ["https://nus.kattis.com/courses/CS2040/CS2040_S1_AY2425/..."]
  }
]
```
```

--------------------------------

### OpenKattis.challenge_ranklist() - Challenge Ladder

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves the top 100 users in the challenge ladder, which focuses on optimization problems. The data can be converted to a DataFrame for analysis.

```APIDOC
## OpenKattis.challenge_ranklist()

### Description
Retrieve the top 100 users in the challenge ladder (optimization problems).

### Method
GET

### Endpoint
/ranklist/challenge

### Parameters
None

### Request Example
```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

challenge_top = kt.challenge_ranklist()
```

### Response
#### Success Response (200)
- **challenge_top** (list) - A list of user rank objects for the challenge ladder, including rank, name, username, score, country, and affiliation.

#### Response Example
```json
[
  {
    "rank": 1,
    "name": "Optimizer",
    "username": "optimizer",
    "score": 99999.9,
    "country_code": "USA",
    "country": "United States",
    "affiliation_code": "mit.edu",
    "affiliation": "MIT"
  }
]
```

### DataFrame Conversion
```python
df = kt.challenge_ranklist().to_df()
print(df[['rank', 'name', 'score', 'country']].head(10))
```
```

--------------------------------

### Plot Problem Distribution (OpenKattis)

Source: https://github.com/russelldash332/autokattis/blob/main/README.md

Generate a plot of the points distribution for solved problems. The plot can be saved to a file or filtered to show only fully solved submissions.

```python
kt.plot_problems()
```

```python
kt.plot_problems(filepath='plot.png')
```

```python
kt.plot_problems(show_partial=False)
```

--------------------------------

### Fetch NUS Kattis Problem Details

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves detailed information for specific NUS Kattis problems, including statistics, submissions, and course offering associations. Supports fetching single or multiple problems, with an option to download associated files.

```python
from autokattis import NUSKattis

kt = NUSKattis('username', 'password')

# Fetch problem with statistics and submissions
info = kt.problem('magicsequence')
# [{'id': 'magicsequence', 'text': 'Problem statement...', 'cpu': '2 seconds',
#   'memory': '1024 MB', 'author': 'Author', 'source': 'CS2040',
#   'statistics': {...}, 'submissions': [...],
#   'offerings': ['https://nus.kattis.com/courses/CS2040/CS2040_S1_AY2425/...']}]

# Fetch with sample files
info = kt.problem('magicsequence', download_files=True)

# Fetch multiple problems
problems = kt.problem(['magicsequence', 'hello', 'zbrka'])
```

--------------------------------

### NUSKattis.problems() - Fetch NUS Problems

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves problems from NUS Kattis, either the problems you have solved or all available problems.

```APIDOC
## NUSKattis.problems()

### Description
Get problems from NUS Kattis - either solved problems or all available problems.

### Method
GET

### Endpoint
/problems

### Parameters
#### Query Parameters
- **show_solved** (boolean) - Optional - If True (default), returns problems solved by the user. If False, returns all available problems.

### Request Example
```python
from autokattis import NUSKattis

kt = NUSKattis('username', 'password')

# Get problems you have solved (default)
solved = kt.problems()

# Get all problems on NUS Kattis
all_problems = kt.problems(show_solved=False)
```

### Response
#### Success Response (200)
- **name** (string) - The name of the problem.
- **id** (string) - The unique identifier of the problem.
- **link** (string) - A URL to the problem on NUS Kattis.

#### Response Example
```json
[
  {
    "name": "Hello World!",
    "id": "hello",
    "link": "https://nus.kattis.com/problems/hello"
  }
]
```
```

--------------------------------

### List NUS Kattis Course Assignments

Source: https://context7.com/russelldash332/autokattis/llms.txt

Fetches all assignments for a specific course offering on NUS Kattis, including their associated problem lists. Requires both the course offering ID and the course ID.

```python
from autokattis import NUSKattis

kt = NUSKattis('username', 'password')

# With explicit course ID
assignments = kt.assignments('CS2040_S1_AY2425', 'CS2040')
```

--------------------------------

### Fetch Kattis Problem Lists

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieve lists of Kattis problems. Use low_detail_mode=True for faster results with minimal data. Supports filtering by solved, partial, tried, and untried problems. Results can be converted to pandas DataFrames.

```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

# Get only solved problems (fast, minimal data)
solved = kt.problems()
# [{'name': 'Hello World!', 'id': 'hello', 'link': 'https://open.kattis.com/problems/hello'}, ...]

# Get solved problems with full details
solved_detailed = kt.problems(low_detail_mode=False)
# [{'name': 'Hello World!', 'id': 'hello', 'fastest': 0.0, 'shortest': 5,
#   'total': 12345, 'acc': 9876, 'difficulty': 1.2, 'category': 'Easy',
#   'link': 'https://open.kattis.com/problems/hello'}, ...]

# Get all problems including untried ones
all_problems = kt.problems(show_solved=True, show_partial=True, show_tried=True, show_untried=True)

# Exclude partial solutions
fully_solved = kt.problems(show_partial=False)

# Convert to pandas DataFrame
df = kt.problems().to_df()
print(df[['id', 'name', 'difficulty']].head())
```

--------------------------------

### OpenKattis.user_ranklist() - Top 100 Users

Source: https://context7.com/russelldash332/autokattis/llms.txt

Retrieves the global top 100 user ranklist. The data can be converted to a DataFrame for grouping and analysis by country.

```APIDOC
## OpenKattis.user_ranklist()

### Description
Retrieve the global top 100 user ranklist.

### Method
GET

### Endpoint
/ranklist/users

### Parameters
None

### Request Example
```python
from autokattis import OpenKattis

kt = OpenKattis('username', 'password')

top_users = kt.user_ranklist()
```

### Response
#### Success Response (200)
- **users** (list) - A list of user rank objects for the top 100 users, including rank, name, username, points, country, and affiliation.

#### Response Example
```json
[
  {
    "rank": 1,
    "name": "Top Coder",
    "username": "topcoder",
    "points": 99999.9,
    "country_code": "USA",
    "country": "United States",
    "affiliation_code": "mit.edu",
    "affiliation": "MIT"
  }
]
```

### DataFrame Conversion
```python
# Group top users by country
df = kt.user_ranklist().to_df()
print(df.groupby('country').size().sort_values(ascending=False).head(10))
```
```