luogu-api-python

luogu-api-python is a Python implementation of the Luogu API. It provides an interface to interact with the Luogu online judge system, allowing users to programmatically manage problems and user operations on Luogu. This library aims to simplify automating tasks on Luogu with easy-to-use methods and classes.

Upstream docs: https://github.com/sjx233/luogu-api-docs

Installation

To install the package, use pip:

$ pip3 install luogu-api-python

To install the package from source, follow these steps:

$ git clone https://github.com/NekoOS-Group/luogu-api-python.git
$ cd luogu-api-python
$ python3 -m pip install .

Usage

Synchronous API

Here is an example of how to use the package:

import pyLuogu

# Initialize the API without cookies
luogu = pyLuogu.luoguAPI()

# Get a list of problems
problems = luogu.get_problem_list().problems
for problem in problems:
    print(problem.title)

Asynchronous API (Experimental)

The package also provides experimental support for async operations:

import asyncio
import pyLuogu

# Initialize the async API without cookies
luogu = pyLuogu.asyncLuoguAPI()

async def main():
    problems = (await luogu.get_problem_list()).problems
    for problem in problems:
        print(problem.title)

asyncio.run(main())

Note: The async API is currently experimental and subject to changes.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Pull Request

1. Fork the repository on GitHub.
2. Clone your forked repository to your local machine:

   $ git clone https://github.com/your-username/luogu-api-python.git
   $ cd luogu-api-python
   

3. Create a new branch for your feature or bugfix:

   $ git checkout -b feature-or-bugfix-name
   

4. Make your changes and commit them with a descriptive commit message:

   $ git add .
   $ git commit -m "Description of your changes"
   

5. Push your changes to your forked repository:

   $ git push origin feature-or-bugfix-name
   

6. Open a pull request on the original repository and provide a detailed description of your changes.

Reporting Issues

If you find a bug or have a feature request, please open an issue on GitHub. Provide as much detail as possible to help us understand and address the issue.

Todo List

API Implementation Status

Core APIs

• Problem API

  • get_problem_list
  • get_problem
  • get_problem_settings
  • update_problem_settings
  • update_testcases_settings
  • create_problem
  • delete_problem
  • transfer_problem
  • download_testcases
  • upload_testcases

• Problem Set API

  • get_problem_set
  • get_problem_set_list

• Contest API

  • get_contest
  • get_contest_list

• User API

  • get_user
  • get_user_info
  • get_user_followings_list
  • get_user_followers_list
  • get_user_blacklist
  • search_user

• Discussion API

  • get_discussion

• Activity(benben) API

  • get_activity

• Team API

  • get_team
  • get_team_member_list
  • get_team_problem_list
  • get_team_problem_set_list
  • get_team_contest_list

• Paste API

  • get_paste

• Artical API

  • get_article
  • get_article_list
  • get_user_article_list
  • get_problem_solutions

• User Operations

  • login
  • logout
  • me
  • submit_code
  • get_created_problem_list
  • get_created_problemset_list
  • get_created_content_list
  • get_created_article_list
  • update_my_setting

• Miscellaneous

  • get_tags
  • get_image
  • get_captcha
  • sign_up

Alternative API Implementations

• asyncLuoguAPI (Experimental)

  • Async versions of all implemented core APIs
  • Performance optimizations
  • Comprehensive error handling

• staticLuoguAPI

  • Initial implementation
  • Documentation

Test Cases and Documentation

Note: Test suite and documentation are planned for implementation after API features are stabilized. This includes:

• Comprehensive test coverage for both sync and async APIs
• API reference documentation with examples
• Integration test scenarios
• Development guides and best practices

These will be prioritized once the core functionality reaches a stable state.