ossapi 3.1.9__tar.gz → 3.3.0__tar.gz

{ossapi-3.1.9 → ossapi-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ossapi
-Version: 3.1.9
+Version: 3.3.0
 Summary: Complete python wrapper for osu! api v2 and v1.
 Author-email: Liam DeVoe <orionldevoe@gmail.com>
 Project-URL: Homepage, https://github.com/circleguard/ossapi
@@ -14,13 +14,14 @@ License-File: LICENSE
 
 # ossapi ([documentation](https://circleguard.github.io/ossapi/)) [![PyPI version](https://badge.fury.io/py/ossapi.svg)](https://pypi.org/project/ossapi/)
 
-ossapi is a python wrapper for the osu! api which has complete coverage of both [api v2](https://osu.ppy.sh/docs/index.html) and [api v1](https://github.com/ppy/osu-api/wiki). ossapi provides both sync (`Ossapi`) and async (`OssapiAsync`) versions for api v2.
+ossapi is the definitive python wrapper for the osu! api. ossapi has complete coverage of [api v2](https://osu.ppy.sh/docs/index.html) and [api v1](https://github.com/ppy/osu-api/wiki), and provides both sync (`Ossapi`) and async (`OssapiAsync`) versions for api v2.
 
 If you need support or would like to contribute, feel free to ask in the `#ossapi` channel of the [circleguard discord](https://discord.gg/e84qxkQ).
 
 * [Installation](#installation)
 * [Quickstart](#quickstart)
 * [Async](#async)
+* [Lazer](#lazer)
 * [Endpoints](#endpoints)
   * [Beatmaps](#endpoints-beatmaps)
   * [Beatmapsets](#endpoints-beatmapsets)
@@ -73,7 +74,7 @@ from ossapi import Ossapi
 api = Ossapi(client_id, client_secret)
 
 # see docs for full list of endpoints
-print(api.user("tybug2").username)
+print(api.user("tybug").username)
 print(api.user(12092800, mode="osu").username)
 print(api.beatmap(221777).id)
 ```
@@ -89,13 +90,29 @@ from ossapi import Ossapi
 api = Ossapi(client_id, client_secret)
 
 async def main():
-    await api.user("tybug2")
+    await api.user("tybug")
 
 asyncio.run(main())
 ```
 
 [Read more about OssapiAsync on the docs.](https://circleguard.github.io/ossapi/async.html)
 
+## Lazer
+
+You can retrieve lazer-specific data (scores, leaderboards, etc) with ossapi:
+
+```python
+from ossapi import Ossapi
+
+api_lazer = Ossapi(client_id, client_secret, domain="lazer")
+
+# best score on the lazer server (lazer + osu scores combined)
+scores = api_lazer.user_scores(12092800, "best")
+print(scores[0].pp)
+```
+
+[Read more about domains on the docs.](https://circleguard.github.io/ossapi/domains.html)
+
 ## Endpoints
 
 All endpoints for api v2.
@@ -170,7 +187,7 @@ All endpoints for api v2.
 
 ## API v1 Usage
 
-You can get your api v1 key at <https://osu.ppy.sh/p/api/>. Note that due to a [redirection bug](https://github.com/ppy/osu-web/issues/2867), you may need to log in and wait 30 seconds before being able to access the api page through the above link.
+You can get your api v1 key at <https://osu.ppy.sh/home/account/edit#legacy-api>.
 
 Basic usage:
 

{ossapi-3.1.9 → ossapi-3.3.0}/README.md

@@ -1,12 +1,13 @@
 # ossapi ([documentation](https://circleguard.github.io/ossapi/)) [![PyPI version](https://badge.fury.io/py/ossapi.svg)](https://pypi.org/project/ossapi/)
 
-ossapi is a python wrapper for the osu! api which has complete coverage of both [api v2](https://osu.ppy.sh/docs/index.html) and [api v1](https://github.com/ppy/osu-api/wiki). ossapi provides both sync (`Ossapi`) and async (`OssapiAsync`) versions for api v2.
+ossapi is the definitive python wrapper for the osu! api. ossapi has complete coverage of [api v2](https://osu.ppy.sh/docs/index.html) and [api v1](https://github.com/ppy/osu-api/wiki), and provides both sync (`Ossapi`) and async (`OssapiAsync`) versions for api v2.
 
 If you need support or would like to contribute, feel free to ask in the `#ossapi` channel of the [circleguard discord](https://discord.gg/e84qxkQ).
 
 * [Installation](#installation)
 * [Quickstart](#quickstart)
 * [Async](#async)
+* [Lazer](#lazer)
 * [Endpoints](#endpoints)
   * [Beatmaps](#endpoints-beatmaps)
   * [Beatmapsets](#endpoints-beatmapsets)
@@ -59,7 +60,7 @@ from ossapi import Ossapi
 api = Ossapi(client_id, client_secret)
 
 # see docs for full list of endpoints
-print(api.user("tybug2").username)
+print(api.user("tybug").username)
 print(api.user(12092800, mode="osu").username)
 print(api.beatmap(221777).id)
 ```
@@ -75,13 +76,29 @@ from ossapi import Ossapi
 api = Ossapi(client_id, client_secret)
 
 async def main():
-    await api.user("tybug2")
+    await api.user("tybug")
 
 asyncio.run(main())
 ```
 
 [Read more about OssapiAsync on the docs.](https://circleguard.github.io/ossapi/async.html)
 
+## Lazer
+
+You can retrieve lazer-specific data (scores, leaderboards, etc) with ossapi:
+
+```python
+from ossapi import Ossapi
+
+api_lazer = Ossapi(client_id, client_secret, domain="lazer")
+
+# best score on the lazer server (lazer + osu scores combined)
+scores = api_lazer.user_scores(12092800, "best")
+print(scores[0].pp)
+```
+
+[Read more about domains on the docs.](https://circleguard.github.io/ossapi/domains.html)
+
 ## Endpoints
 
 All endpoints for api v2.
@@ -156,7 +173,7 @@ All endpoints for api v2.
 
 ## API v1 Usage
 
-You can get your api v1 key at <https://osu.ppy.sh/p/api/>. Note that due to a [redirection bug](https://github.com/ppy/osu-web/issues/2867), you may need to log in and wait 30 seconds before being able to access the api page through the above link.
+You can get your api v1 key at <https://osu.ppy.sh/home/account/edit#legacy-api>.
 
 Basic usage:
 

{ossapi-3.1.9 → ossapi-3.3.0}/ossapi/__init__.py

@@ -6,7 +6,7 @@ from importlib import metadata
 
 from ossapi.ossapi import (OssapiV1, ReplayUnavailableException,
     InvalidKeyException, APIException)
-from ossapi.ossapiv2 import Ossapi, Grant, Scope
+from ossapi.ossapiv2 import Ossapi, Grant, Scope, Domain
 from ossapi.models import (Beatmap, BeatmapCompact, BeatmapUserScore,
     ForumTopicAndPosts, Search, CommentBundle, Cursor, Score,
     BeatmapsetSearchResult, ModdingHistoryEventsBundle, User, Rankings,
@@ -17,7 +17,8 @@ from ossapi.models import (Beatmap, BeatmapCompact, BeatmapUserScore,
     UserCompact, BeatmapsetCompact, ForumPoll, Room, RoomPlaylistItem,
     RoomPlaylistItemMod, RoomLeaderboardScore, RoomLeaderboardUserScore,
     RoomLeaderboard, Match, Matches, MatchResponse, ScoreMatchInfo, MatchGame,
-    MatchEventDetail, MatchEvent, ScoringType, TeamType)
+    MatchEventDetail, MatchEvent, ScoringType, TeamType, StatisticsVariant,
+    Events)
 from ossapi.enums import (GameMode, ScoreType, RankingFilter, RankingType,
     UserBeatmapType, BeatmapDiscussionPostSort, UserLookupKey,
     BeatmapsetEventType, CommentableType, CommentSort, ForumTopicSort,
@@ -26,7 +27,7 @@ from ossapi.enums import (GameMode, ScoreType, RankingFilter, RankingType,
     BeatmapsetSearchCategory, BeatmapsetSearchMode,
     BeatmapsetSearchExplicitContent, BeatmapsetSearchLanguage,
     BeatmapsetSearchGenre, NewsPostKey, BeatmapsetSearchSort, RoomType,
-    RoomCategory, RoomSearchType, MatchEventType)
+    RoomCategory, RoomSearchType, MatchEventType, Variant, EventsSort)
 from ossapi.mod import Mod
 from ossapi.replay import Replay
 from ossapi.encoder import ModelEncoder, serialize_model
@@ -42,7 +43,7 @@ __all__ = [
     "OssapiV1", "ReplayUnavailableException", "InvalidKeyException",
     "APIException",
     # OssapiV2 core
-    "Ossapi", "OssapiAsync", "Grant", "Scope",
+    "Ossapi", "OssapiAsync", "Grant", "Scope", "Domain",
     # OssapiV2 models
     "Beatmap", "BeatmapCompact", "BeatmapUserScore", "ForumTopicAndPosts",
     "Search", "CommentBundle", "Cursor", "Score", "BeatmapsetSearchResult",
@@ -55,7 +56,7 @@ __all__ = [
     "Room", "RoomPlaylistItem", "RoomPlaylistItemMod", "RoomLeaderboardScore",
     "RoomLeaderboardUserScore", "RoomLeaderboard", "Match", "Matches",
     "MatchResponse", "ScoreMatchInfo", "MatchGame", "MatchEventDetail",
-    "MatchEvent",
+    "MatchEvent", "StatisticsVariant", "Events",
     # OssapiV2 enums
     "GameMode", "ScoreType", "RankingFilter", "RankingType",
     "UserBeatmapType", "BeatmapDiscussionPostSort", "UserLookupKey",
@@ -66,7 +67,7 @@ __all__ = [
     "BeatmapsetSearchExplicitContent", "BeatmapsetSearchLanguage",
     "BeatmapsetSearchGenre", "NewsPostKey", "BeatmapsetSearchSort", "RoomType",
     "RoomCategory", "RoomSearchType", "MatchEventType", "ScoringType",
-    "TeamType",
+    "TeamType", "Variant", "EventsSort",
     # OssapiV2 exceptions
     "AccessDeniedError", "TokenExpiredError", "InsufficientScopeError",
     # misc

{ossapi-3.1.9 → ossapi-3.3.0}/ossapi/enums.py

@@ -88,10 +88,8 @@ class UserAccountHistoryType(EnumModel):
     SILENCE = "silence"
 
 class MessageType(EnumModel):
-    DISQUALIFY = "disqualify"
     HYPE = "hype"
     MAPPER_NOTE = "mapper_note"
-    NOMINATION_RESET = "nomination_reset"
     PRAISE = "praise"
     PROBLEM = "problem"
     REVIEW = "review"
@@ -217,6 +215,7 @@ class RoomCategory(EnumModel):
     # 430a2/resources/js/interfaces/room-json.ts#L7
     NORMAL = "normal"
     SPOTLIGHT = "spotlight"
+    FEATURED_ARTIST = "featured_artist"
 
 class MatchEventType(EnumModel):
     # https://github.dev/ppy/osu-web/blob/3d1586392102b05f2a3b264905c4dbb7b2
@@ -246,6 +245,10 @@ class TeamType(EnumModel):
     TEAM_VS = "team-vs"
     TAG_TEAM_VS = "tag-team-vs"
 
+class Variant(EnumModel):
+    # can't start a python identifier with an integer
+    KEY_4 = "4k"
+    KEY_7 = "7k"
 
 
 # ===============
@@ -298,6 +301,7 @@ class ChannelType(EnumModel):
     TEMPORARY = "TEMPORARY"
     PM = "PM"
     GROUP = "GROUP"
+    ANNOUNCE = "ANNOUNCE"
 
 class CommentableType(EnumModel):
     NEWS_POST = "news_post"
@@ -379,8 +383,8 @@ class BeatmapsetSearchLanguage(EnumModel):
     ENGLISH = 2
     JAPANESE = 3
     CHINESE = 4
-    KOREAN = 6
     INSTRUMENTAL = 5
+    KOREAN = 6
     FRENCH = 7
     GERMAN = 8
     SWEDISH = 9
@@ -425,6 +429,9 @@ class RoomSearchType(EnumModel):
     PARTICIPATED = "participated"
     ENDED = "ended"
 
+class EventsSort(EnumModel):
+    NEW = "id_desc"
+    OLD = "id_asc"
 
 
 # =================
@@ -609,6 +616,14 @@ class ForumPostBody(Model):
     html: str
     raw: str
 
+class ForumPollText(Model):
+    bbcode: str
+    html: str
+
+class ForumPollTitle(Model):
+    bbcode: str
+    html: str
+
 class ReviewsConfig(Model):
     max_blocks: int
 

{ossapi-3.1.9 → ossapi-3.3.0}/ossapi/models.py

@@ -16,7 +16,8 @@ from ossapi.enums import (UserAccountHistory, ProfileBanner, UserBadge, Country,
     BeatmapsetEventType, UserRelationType, UserLevel, UserGradeCounts,
     GithubUser, ChangelogSearch, ForumTopicType, ForumPostBody, ForumTopicSort,
     ChannelType, ReviewsConfig, NewsSearch, Nomination, RankHighest, RoomType,
-    RoomCategory, MatchEventType, ScoringType, TeamType)
+    RoomCategory, MatchEventType, ScoringType, TeamType, Variant, ForumPollText,
+    ForumPollTitle)
 from ossapi.utils import Datetime, Model, BaseModel, Field
 
 T = TypeVar("T")
@@ -86,7 +87,6 @@ class UserCompact(Model):
     # ---------------
     avatar_url: str
     country_code: str
-    default_group: str
     id: int
     is_active: bool
     is_bot: bool
@@ -107,14 +107,13 @@ class UserCompact(Model):
     blocks: Optional[UserRelation]
     country: Optional[Country]
     cover: Optional[Cover]
+    default_group: Optional[str]
     favourite_beatmapset_count: Optional[int]
-    # undocumented
     follow_user_mapping: Optional[List[int]]
     follower_count: Optional[int]
     friends: Optional[List[UserRelation]]
     graveyard_beatmapset_count: Optional[int]
     groups: Optional[List[UserGroup]]
-    # undocumented
     guest_beatmapset_count: Optional[int]
     is_admin: Optional[bool]
     is_bng: Optional[bool]
@@ -130,7 +129,11 @@ class UserCompact(Model):
     mapping_follower_count: Optional[int]
     monthly_playcounts: Optional[List[UserMonthlyPlaycount]]
     page: Optional[UserPage]
+    pending_beatmapset_count: Optional[int]
     previous_usernames: Optional[List[str]]
+    # deprecated, replaced by rank_history
+    rankHistory: Optional[RankHistory]
+    rank_history: Optional[RankHistory]
     # deprecated, replaced by ranked_beatmapset_count
     ranked_and_approved_beatmapset_count: Optional[int]
     ranked_beatmapset_count: Optional[int]
@@ -143,13 +146,10 @@ class UserCompact(Model):
     support_level: Optional[int]
     # deprecated, replaced by pending_beatmapset_count
     unranked_beatmapset_count: Optional[int]
-    pending_beatmapset_count: Optional[int]
     unread_pm_count: Optional[int]
     user_achievements: Optional[List[UserAchievement]]
     user_preferences: Optional[UserProfileCustomization]
-    rank_history: Optional[RankHistory]
-    # deprecated, replaced by rank_history
-    rankHistory: Optional[RankHistory]
+
 
     def expand(self) -> User:
         return self._fk_user(self.id)
@@ -264,17 +264,17 @@ class BeatmapsetCompact(Model):
     creator: str
     favourite_count: int
     id: int
+    nsfw: bool
+    offset: int
     play_count: int
     preview_url: str
     source: str
     status: RankStatus
+    spotlight: bool
     title: str
     title_unicode: str
     user_id: int
     video: bool
-    nsfw: bool
-    offset: int
-    spotlight: bool
     # documented as being in `Beatmapset` only, but returned by
     # `api.beatmapset_events` which uses a `BeatmapsetCompact`.
     hype: Optional[Hype]
@@ -283,6 +283,7 @@ class BeatmapsetCompact(Model):
     # ---------------
     beatmaps: Optional[List[Beatmap]]
     converts: Optional[Any]
+    current_nominations: Optional[List[Nomination]]
     current_user_attributes: Optional[Any]
     description: Optional[Any]
     discussions: Optional[Any]
@@ -291,12 +292,12 @@ class BeatmapsetCompact(Model):
     has_favourited: Optional[bool]
     language: Optional[Any]
     nominations: Optional[Any]
+    pack_tags: Optional[List[str]]
     ratings: Optional[Any]
     recent_favourites: Optional[Any]
     related_users: Optional[Any]
-    _user: Optional[UserCompact] = Field(name="user")
-    # undocumented
     track_id: Optional[int]
+    _user: Optional[UserCompact] = Field(name="user")
 
     def expand(self) -> Beatmapset:
         return self._fk_beatmapset(self.id)
@@ -308,6 +309,7 @@ class Beatmapset(BeatmapsetCompact):
     availability: Availability
     bpm: float
     can_be_hyped: bool
+    deleted_at: Optional[Datetime]
     discussion_enabled: bool
     discussion_locked: bool
     is_scoreable: bool
@@ -319,9 +321,6 @@ class Beatmapset(BeatmapsetCompact):
     storyboard: bool
     submitted_date: Optional[Datetime]
     tags: str
-    current_nominations: Optional[List[Nomination]]
-    deleted_at: Optional[Datetime]
-    pack_tags: List[str]
 
     def expand(self) -> Beatmapset:
         return self
@@ -434,18 +433,18 @@ class Comment(Model):
 class CommentBundle(Model):
     commentable_meta: List[CommentableMeta]
     comments: List[Comment]
+    cursor: CursorT
     has_more: bool
     has_more_id: Optional[int]
     included_comments: List[Comment]
     pinned_comments: Optional[List[Comment]]
+    # TODO this should be type CommentSort
     sort: str
     top_level_count: Optional[int]
     total: Optional[int]
     user_follow: bool
     user_votes: List[int]
     users: List[UserCompact]
-    # undocumented
-    cursor: CursorT
 
 class ForumPost(Model):
     created_at: Datetime
@@ -477,11 +476,27 @@ class ForumTopic(Model):
     type: ForumTopicType
     updated_at: Datetime
     user_id: int
-    poll: Any
+    poll: Optional[ForumPollModel]
 
     def user(self) -> User:
         return self._fk_user(self.user_id)
 
+class ForumPollModel(Model):
+    allow_vote_change: bool
+    ended_at: Optional[Datetime]
+    hide_incomplete_results: bool
+    last_vote_at: Optional[Datetime]
+    max_votes: int
+    options: List[ForumPollOption]
+    started_at: Datetime
+    title: ForumPollTitle
+    total_vote_count: int
+
+class ForumPollOption(Model):
+    id: int
+    text: ForumPollText
+    vote_count: Optional[int]
+
 class ForumTopicAndPosts(Model):
     cursor: CursorT
     search: ForumTopicSearch
@@ -579,13 +594,9 @@ class BeatmapsetDiscussion(Model):
     can_be_resolved: bool
     can_grant_kudosu: bool
     created_at: Datetime
-    # documented as non-optional, api.beatmapset_events() might give a null
-    # response for this? but very rarely. need to find a repro case
     current_user_attributes: Any
     updated_at: Datetime
     deleted_at: Optional[Datetime]
-    # similarly as for current_user_attributes, in the past this has been null
-    # but can't find a repro case
     last_post_at: Datetime
     kudosu_denied: bool
     starting_post: Optional[BeatmapsetDiscussionPost]
@@ -613,6 +624,8 @@ class BeatmapsetDiscussionVote(Model):
     beatmapset_discussion_id: int
     created_at: Datetime
     updated_at: Datetime
+    # TODO is this field ever actually returned? not documented and can't find
+    # a repro case.
     cursor_string: Optional[str]
 
     def user(self):
@@ -731,6 +744,7 @@ class Build(Model):
     version: Optional[str]
     changelog_entries: Optional[List[ChangelogEntry]]
     versions: Optional[Versions]
+    youtube_id: Optional[str]
 
 class Versions(Model):
     next: Optional[Build]
@@ -851,8 +865,8 @@ class BeatmapDifficultyAttributes(Model):
     stamina_difficulty: Optional[float]
     rhythm_difficulty: Optional[float]
     colour_difficulty: Optional[float]
-    approach_raty: Optional[float]
-    great_hit_windoy: Optional[float]
+    approach_rate: Optional[float]
+    great_hit_window: Optional[float]
 
     # ctb attributes
     approach_rate: Optional[float]
@@ -861,6 +875,9 @@ class BeatmapDifficultyAttributes(Model):
     great_hit_window: Optional[float]
     score_multiplier: Optional[float]
 
+class Events(Model):
+    cursor_string: str
+    events: List[Event]
 
 
 # ================
@@ -1032,15 +1049,14 @@ class ChatChannel(Model):
     channel_id: int
     description: Optional[str]
     icon: Optional[str]
-    # documented as non-optional (to see that it can be null, pm tillerino)
     moderated: Optional[bool]
     name: str
     type: ChannelType
     uuid: Optional[str]
+    message_length_limit: int
 
     # optional fields
     # ---------------
-    first_message_id: Optional[int]
     last_message_id: Optional[int]
     last_read_id: Optional[int]
     recent_messages: Optional[List[ChatMessage]]
@@ -1089,31 +1105,38 @@ class UserRelation(Model):
     def target(self) -> Union[User, UserCompact]:
         return self._fk_user(self.target_id, existing=self.target)
 
+class StatisticsVariant(Model):
+    mode: GameMode
+    variant: Variant
+    country_rank: Optional[int]
+    global_rank: Optional[int]
+    pp: float
 
 class UserStatistics(Model):
-    level: UserLevel
-    pp: float
-    ranked_score: int
+    count_100: int
+    count_300: int
+    count_50: int
+    count_miss: int
+    country_rank: Optional[int]
+    grade_counts: UserGradeCounts
     hit_accuracy: float
+    is_ranked: bool
+    level: UserLevel
+    maximum_combo: int
     play_count: int
     play_time: int
-    total_score: int
-    total_hits: int
-    maximum_combo: int
-    replays_watched_by_others: int
-    is_ranked: bool
-    grade_counts: UserGradeCounts
-    country_rank: Optional[int]
+    pp: float
+    pp_exp: float
     global_rank: Optional[int]
+    global_rank_exp: Optional[float]
+    # deprecated, replaced by global_rank and country_rank
     rank: Optional[Any]
+    ranked_score: int
+    replays_watched_by_others: int
+    total_hits: int
+    total_score: int
     user: Optional[UserCompact]
-    variants: Optional[Any]
-    global_rank_exp: Optional[float]
-    pp_exp: float
-    count_100: int
-    count_300: int
-    count_50: int
-    count_miss: int
+    variants: Optional[List[StatisticsVariant]]
 
 class UserStatisticsRulesets(Model):
     # undocumented