fix ci

* packlist & songlist importer

.github/workflows/build-and-draft-release.yml

@@ -0,0 +1,48 @@
+name: "Build and draft a release"
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: write
+  discussions: write
+
+jobs:
+  build-and-draft-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python environment
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Remove `v` in tag name
+        uses: mad9000/actions-find-and-replace-string@5
+        id: tagNameReplaced
+        with:
+          source: ${{ github.ref_name }}
+          find: "v"
+          replace: ""
+
+      - name: Draft a release
+        uses: softprops/action-gh-release@v2
+        with:
+          discussion_category_name: New releases
+          draft: true
+          generate_release_notes: true
+          files: |
+            dist/arcaea_offline-${{ steps.tagNameReplaced.outputs.value }}*.whl
+            dist/arcaea-offline-${{ steps.tagNameReplaced.outputs.value }}.tar.gz

.github/workflows/main.yml

@@ -0,0 +1,41 @@
+name: test & lint
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    types: [opened, reopened]
+  workflow_dispatch:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dev dependencies
+        run: 'pip install .[dev]'
+      - name: Run tests
+        run: 'python -m pytest -v'
+
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dev dependencies
+        run: 'pip install .[dev]'
+      - name: Run linter
+        run: 'ruff check'

.pre-commit-config.yaml

@@ -4,11 +4,10 @@ repos:
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace
-  - repo: https://github.com/psf/black
-    rev: 23.1.0
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
     hooks:
-      - id: black
-  - repo: https://github.com/PyCQA/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format

.sourcery.yaml

@@ -0,0 +1,2 @@
+rule_settings:
+  python_version: '3.8'

LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

README.md

@@ -1,22 +1,39 @@
 # Arcaea Offline
 
-> 接受 <i><b>lr</b><sub>lowiro</sub></i> 的一切
+English | [简体中文](./README.zh_Hans.md)
 
-![Excel | Eternity](./assets/excel_eternity.png "Excel | Eternity")
+<span>
+  <img src="./assets/banner.png" style="height: 175px; object-fit: contain;">
+</span>
+
+> Accept <i><b>lr</b><sub>lowiro</sub></i>
 
 ## WIP
 
-This project is under active development, thus it is unstable and API may change frequently.
+> **Warning**
+> This project is under active development, thus it is unstable and API may change frequently.
 
-## 这事什么？
+## What is this？
 
-这是用于计算 [Arcaea](https://arcaea.lowiro.com/) 中，玩家潜力值的 [B30 和 R10](https://wiki.arcaea.cn/潜力值#整体潜力值计算) 部分的程序。
+This is the core library of `Arcaea Offline`, designed to manage player scores, calculate their potential, and provide various useful tools.
 
-## 这怎么用？
+## How to use this？
 
-这个存储库是相对基础的，提供操作数据库等“底层”操作的 python 库。要使用该库，请查阅 API 手册（还没写）。
+This repository is a python library.
 
-如果您正寻找 GUI，请前往 [283375/arcaea-offline-pyside-ui](https://github.com/283375/arcaea-offline-pyside-ui) 了解详情。
+For general users, if you don't know what is a "library", you may be interested about [this GUI](https://github.com/283375/arcaea-offline-pyside-ui).
+
+For developers, the documentation is under construction. Check back later!
+
+## License
+
+This file is part of arcaea-offline.
+
+arcaea-offline is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+arcaea-offline is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with arcaea-offline. If not, see <https://www.gnu.org/licenses/>.
 
 ## Credits
 

README.zh_Hans.md

@@ -0,0 +1,38 @@
+# Arcaea Offline
+
+<span>
+  <img src="./assets/banner.png" style="height: 175px; object-fit: contain;">
+</span>
+
+> 接受 <i><b>lr</b><sub>lowiro</sub></i> 的一切
+
+## WIP
+
+> **Warning**
+> 该项目正处于早期开发阶段，不能保证稳定性，且 API 可能随时变动。
+
+## 这是什么？
+
+这是 `Arcaea Offline` 的核心依赖库，用于维护分数数据库、计算潜力值，并提供一些实用工具。
+
+## 这怎么用？
+
+该仓库是一个 python 库。
+
+对普通用户，如果你不知道“库”是什么，你应该对[这个 GUI](https://github.com/283375/arcaea-offline-pyside-ui) 更感兴趣。
+
+对开发者，文档仍在建设当中，敬请期待。
+
+## 许可声明
+
+本文件是 arcaea-offline 的一部分。
+
+arcaea-offline 是自由软件：你可以再分发之和/或依照由自由软件基金会发布的 GNU 通用公共许可证修改之，无论是版本 3 许可证，还是（按你的决定）任何以后版都可以。
+
+发布 arcaea-offline 是希望它能有用，但是并无保障；甚至连可销售和符合某个特定的目的都不保证。请参看 GNU 通用公共许可证，了解详情。
+
+你应该随程序获得一份 GNU 通用公共许可证的复本。如果没有，请看 <https://www.gnu.org/licenses/>。
+
+## Credits
+
+[Arcaea-Infinity/ArcaeaSongDatabase](https://github.com/Arcaea-Infinity/ArcaeaSongDatabase)

assets/logo.svg

@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="500"
+   height="500"
+   viewBox="0 0 500 500"
+   version="1.1"
+   id="svg1"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <defs
+     id="defs1">
+    <linearGradient
+       id="linearGradient1">
+      <stop
+         style="stop-color:#b9b6d8;stop-opacity:1;"
+         offset="0"
+         id="stop1" />
+      <stop
+         style="stop-color:#b9b6d8;stop-opacity:0;"
+         offset="1"
+         id="stop4" />
+    </linearGradient>
+    <linearGradient
+       id="linearGradient2">
+      <stop
+         style="stop-color:#413d5c;stop-opacity:1;"
+         offset="0.1"
+         id="stop2" />
+      <stop
+         style="stop-color:#34333e;stop-opacity:1;"
+         offset="0.89999998"
+         id="stop3" />
+    </linearGradient>
+    <linearGradient
+       xlink:href="#linearGradient2"
+       id="linearGradient3"
+       x1="87.5"
+       y1="165.07216"
+       x2="418.75003"
+       y2="359.92786"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       xlink:href="#linearGradient1"
+       id="linearGradient6"
+       x1="250"
+       y1="55.144306"
+       x2="250"
+       y2="446.85571"
+       gradientUnits="userSpaceOnUse" />
+  </defs>
+  <g
+     id="layer1">
+    <path
+       style="display:inline;fill:url(#linearGradient3);fill-opacity:1;stroke:none;stroke-width:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 25,275 150,55.144305 H 350 L 475,275 362.50004,444.8557 H 137.49996 Z"
+       id="path16" />
+    <path
+       style="display:inline;fill:#626080;fill-opacity:1;stroke:none;stroke-width:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 150,55.144305 110.28321,125 H 389.71679 L 350,55.144305 Z"
+       id="path7" />
+    <path
+       style="display:inline;fill:none;fill-opacity:1;stroke:url(#linearGradient6);stroke-width:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 25,275 150,55.144305 H 350 L 475,275 362.50004,444.8557 H 137.49996 Z"
+       id="path9" />
+    <path
+       style="font-size:50px;font-family:GeosansLight;-inkscape-font-specification:GeosansLight;letter-spacing:-1px;fill:#dcdaf2;stroke-width:20"
+       d="m 174.4,81.347151 q 0,-4.05 -2.8,-6.45 -2.8,-2.4 -6.9,-2.4 H 156 v 35.699999 h 2 V 90.347151 h 6.7 q 4.1,0 6.9,-2.5 2.8,-2.4 2.8,-6.5 z m -2.05,0 q 0,3.25 -2.2,5.15 -2.2,1.8 -5.5,1.8 H 158 v -13.75 h 6.65 q 3.35,0 5.4,1.7 2.3,1.85 2.3,5.1 z m 41.19999,9 q 0,-8.1 -5.15,-13.25 -5.2,-5.1 -13.25,-5.1 -8.1,0 -13.25,5.15 -5.1,5.1 -5.1,13.2 0,8.1 5.15,13.249999 5.1,5.1 13.2,5.1 8.1,0 13.25,-5.15 5.15,-5.099999 5.15,-13.199999 z m -2.05,0 q 0,7.25 -4.55,11.799999 -4.6,4.5 -11.8,4.5 -7.15,0 -11.75,-4.6 -4.55,-4.549999 -4.55,-11.699999 0,-7.15 4.6,-11.75 4.6,-4.6 11.7,-4.6 7.2,0 11.8,4.6 4.55,4.55 4.55,11.75 z m 17.10003,-15.8 v -2.05 h -17.85 v 2.05 h 7.9 v 33.649999 h 2.05 V 74.547151 Z m 19.09996,33.649999 v -2.05 h -15.1 V 89.747151 h 15.1 v -2.2 h -15.1 v -13 h 15.1 v -2.05 h -17.15 v 35.699999 z m 31.94995,0.6 V 72.497151 h -2.05 v 30.999999 l -26.65,-31.249999 v 35.949999 h 2 V 77.897151 Z m 19.80005,-34.249999 v -2.05 h -17.85 v 2.05 h 7.9 v 33.649999 h 2.05 V 74.547151 Z M 303.4,108.19715 V 72.497151 h -2 v 35.699999 z m 32.84999,0 -14.3,-36.849999 -14.25,36.849999 h 2 l 4.15,-10.699999 h 16.25 l 4.1,10.699999 z m -7,-12.749999 h -14.6 l 7.3,-18.9 z m 21.09999,12.749999 v -2.05 h -10.05 V 72.497151 h -2 v 35.699999 z"
+       id="text23"
+       aria-label="POTENTIAL" />
+    <path
+       id="path3"
+       style="display:inline;fill:#c6c3e5;stroke-width:4"
+       d="m 250,170 c -32.54103,0.0757 -61.79382,19.85476 -73.98633,50.02539 -0.3378,-0.0116 -0.67571,-0.02 -1.01367,-0.0254 -30.3756,0 -55,24.6244 -55,55 0,30.3756 24.6244,55 55,55 h 75 39.08594 C 268.71234,317.72216 255,295.37888 255,270 255,235.53617 280.28555,206.6766 313.20703,201.02148 298.19408,181.63471 274.93594,170.00868 250,170 Z m 111.87305,84.33984 -52.53321,52.53321 C 314.13799,308.88757 319.42648,310 325,310 c 22.269,0 40,-17.731 40,-40 0,-5.57352 -1.11243,-10.86201 -3.12695,-15.66016 z"
+       transform="translate(-2.5,20)" />
+    <path
+       id="circle14"
+       style="color:#000000;fill:#dcdaf2;-inkscape-stroke:none"
+       d="M 325 210 C 291.9222 210 265 236.9222 265 270 C 265 303.0778 291.9222 330 325 330 C 358.0778 330 385 303.0778 385 270 C 385 236.9222 358.0778 210 325 210 z M 325 220 C 337.03042 220 348.04772 224.22367 356.66211 231.26758 L 286.26758 301.66211 C 279.22367 293.04772 275 282.03042 275 270 C 275 242.3266 297.3266 220 325 220 z M 363.73242 238.33789 C 370.77633 246.95228 375 257.96958 375 270 C 375 297.6734 352.6734 320 325 320 C 312.96958 320 301.95228 315.77633 293.33789 308.73242 L 363.73242 238.33789 z "
+       transform="translate(-2.5,20)" />
+  </g>
+</svg>

pyproject.toml

@@ -4,28 +4,50 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arcaea-offline"
-version = "0.1.0"
+version = "0.2.2"
 authors = [{ name = "283375", email = "log_283375@163.com" }]
 description = "Manage your local Arcaea score database."
 readme = "README.md"
 requires-python = ">=3.8"
-dependencies = [
-  "beautifulsoup4==4.12.2",
-  "SQLAlchemy==2.0.20",
-  "SQLAlchemy-Utils==0.41.1",
-]
+dependencies = ["SQLAlchemy==2.0.20", "SQLAlchemy-Utils==0.41.1"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Programming Language :: Python :: 3",
 ]
 
+[project.optional-dependencies]
+dev = ["ruff~=0.4", "pre-commit~=3.3", "pytest~=7.4", "tox~=4.11"]
+
 [project.urls]
 "Homepage" = "https://github.com/283375/arcaea-offline"
 "Bug Tracker" = "https://github.com/283375/arcaea-offline/issues"
 
-[tool.isort]
-profile = "black"
-src_paths = ["src/arcaea_offline"]
-
 [tool.pyright]
-ignore = ["**/__debug*.*"]
+ignore = ["build/"]
+
+[tool.ruff.lint]
+# Full list: https://docs.astral.sh/ruff/rules
+select = [
+  "E",   # pycodestyle (Error)
+  "W",   # pycodestyle (Warning)
+  "F",   # pyflakes
+  "I",   # isort
+  "PL",  # pylint
+  "N",   # pep8-naming
+  "FBT", # flake8-boolean-trap
+  "A",   # flake8-builtins
+  "DTZ", # flake8-datetimez
+  "LOG", # flake8-logging
+  "Q",   # flake8-quotes
+  "G",   # flake8-logging-format
+  "PIE", # flake8-pie
+  "PT",  # flake8-pytest-style
+]
+ignore = [
+  "E501", # line-too-long
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+  "PLR2004", # magic-value-comparison
+]

requirements.dev.txt

@@ -1,3 +1,4 @@
-black==23.3.0
-isort==5.12.0
-pre-commit==3.3.1
+ruff~=0.4
+pre-commit~=3.3
+pytest~=7.4
+tox~=4.11

requirements.txt

@@ -1,3 +1,2 @@
-beautifulsoup4==4.12.2
 SQLAlchemy==2.0.20
 SQLAlchemy-Utils==0.41.1

src/arcaea_offline/calculate.py

@@ -1,48 +0,0 @@
-from decimal import Decimal
-from math import floor
-from typing import Dict, List
-
-from .models.scores import Calculated
-
-
-def calculate_score_range(notes: int, pure: int, far: int):
-    single_note_score = 10000000 / Decimal(notes)
-
-    actual_score = floor(
-        single_note_score * pure + single_note_score * Decimal(0.5) * far
-    )
-    return (actual_score, actual_score + pure)
-
-
-def calculate_potential(_constant: float, score: int) -> Decimal:
-    constant = Decimal(_constant)
-    if score >= 10000000:
-        return constant + 2
-    elif score >= 9800000:
-        return constant + 1 + (Decimal(score - 9800000) / 200000)
-    else:
-        return max(Decimal(0), constant + (Decimal(score - 9500000) / 300000))
-
-
-def calculate_shiny_pure(notes: int, score: int, pure: int, far: int) -> int:
-    single_note_score = 10000000 / Decimal(notes)
-    actual_score = single_note_score * pure + single_note_score * Decimal(0.5) * far
-    return score - floor(actual_score)
-
-
-def get_b30_calculated_list(calculated_list: List[Calculated]) -> List[Calculated]:
-    best_scores: Dict[str, Calculated] = {}
-    for calculated in calculated_list:
-        key = f"{calculated.song_id}_{calculated.rating_class}"
-        stored = best_scores.get(key)
-        if stored and stored.score < calculated.score or not stored:
-            best_scores[key] = calculated
-    ret_list = list(best_scores.values())
-    ret_list = sorted(ret_list, key=lambda c: c.potential, reverse=True)[:30]
-    return ret_list
-
-
-def calculate_b30(calculated_list: List[Calculated]) -> Decimal:
-    ptt_list = [Decimal(c.potential) for c in get_b30_calculated_list(calculated_list)]
-    sum_ptt_list = sum(ptt_list)
-    return (sum_ptt_list / len(ptt_list)) if sum_ptt_list else Decimal("0.0")

src/arcaea_offline/calculators/__init__.py

@@ -0,0 +1,3 @@
+from .play_result import PlayResultCalculators
+
+__all__ = ["PlayResultCalculators"]

src/arcaea_offline/calculators/play_result.py

@@ -0,0 +1,105 @@
+from decimal import Decimal
+from math import floor
+from typing import Tuple, TypedDict, Union
+
+from arcaea_offline.constants.play_result import ScoreLowerLimits
+
+
+class PlayResultCalculators:
+    @staticmethod
+    def score_possible_range(notes: int, pure: int, far: int) -> tuple[int, int]:
+        """
+        Returns the possible range of score based on the given values.
+
+        The first integer of returned tuple is the lower limit of the score,
+        and the second integer is the upper limit.
+
+        For example, ...
+        """
+        single_note_score = 10000000 / Decimal(notes)
+
+        actual_score = floor(
+            single_note_score * pure + single_note_score * Decimal(0.5) * far
+        )
+        return (actual_score, actual_score + pure)
+
+    @staticmethod
+    def shiny_pure(notes: int, score: int, pure: int, far: int) -> int:
+        single_note_score = 10000000 / Decimal(notes)
+        actual_score = single_note_score * pure + single_note_score * Decimal(0.5) * far
+        return score - floor(actual_score)
+
+    @staticmethod
+    def score_modifier(score: int) -> Decimal:
+        """
+        Returns the score modifier of the given score
+
+        https://arcaea.fandom.com/wiki/Potential#Score_Modifier
+
+        :param score: The score of the play result, e.g. 9900000
+        :return: The modifier of the given score, e.g. Decimal("1.5")
+        """
+        if not isinstance(score, int):
+            raise TypeError("score must be an integer")
+        if score < 0:
+            raise ValueError("score cannot be negative")
+
+        if score >= 10000000:
+            return Decimal(2)
+        if score >= 9800000:
+            return Decimal(1) + (Decimal(score - 9800000) / 200000)
+        return Decimal(score - 9500000) / 300000
+
+    @classmethod
+    def play_rating(cls, score: int, constant: int) -> Decimal:
+        """
+        Returns the play rating of the given score
+
+        https://arcaea.fandom.com/wiki/Potential#Play_Rating
+
+        :param constant: The (constant * 10) of the played chart, e.g. 120 for Testify[BYD]
+        :param score: The score of the play result, e.g. 10002221
+        :return: The play rating of the given values, e.g. Decimal("14.0")
+        """
+        if not isinstance(score, int):
+            raise TypeError("score must be an integer")
+        if not isinstance(constant, int):
+            raise TypeError("constant must be an integer")
+        if score < 0:
+            raise ValueError("score cannot be negative")
+        if constant < 0:
+            raise ValueError("constant cannot be negative")
+
+        score_modifier = cls.score_modifier(score)
+        return max(Decimal(0), Decimal(constant) / 10 + score_modifier)
+
+    class ConstantsFromPlayRatingResult(TypedDict):
+        EX_PLUS: Tuple[Decimal, Decimal]
+        EX: Tuple[Decimal, Decimal]
+        AA: Tuple[Decimal, Decimal]
+        A: Tuple[Decimal, Decimal]
+        B: Tuple[Decimal, Decimal]
+        C: Tuple[Decimal, Decimal]
+
+    @classmethod
+    def constants_from_play_rating(
+        cls, play_rating: Union[Decimal, str, float, int]
+    ) -> ConstantsFromPlayRatingResult:
+        play_rating = Decimal(play_rating)
+
+        def _result(score_upper: int, score_lower: int) -> Tuple[Decimal, Decimal]:
+            upper_score_modifier = cls.score_modifier(score_upper)
+            lower_score_modifier = cls.score_modifier(score_lower)
+            return (
+                play_rating - upper_score_modifier,
+                play_rating - lower_score_modifier,
+            )
+
+        return {
+            "EX_PLUS": _result(10000000, ScoreLowerLimits.EX_PLUS),
+            "EX": _result(ScoreLowerLimits.EX_PLUS - 1, ScoreLowerLimits.EX),
+            "AA": _result(ScoreLowerLimits.EX - 1, ScoreLowerLimits.AA),
+            "A": _result(ScoreLowerLimits.AA - 1, ScoreLowerLimits.A),
+            "B": _result(ScoreLowerLimits.A - 1, ScoreLowerLimits.B),
+            "C": _result(ScoreLowerLimits.B - 1, ScoreLowerLimits.C),
+        }

src/arcaea_offline/calculators/world/__init__.py

@@ -0,0 +1,25 @@
+from ._common import MemoriesStepBooster, PartnerBonus, WorldPlayResult
+from .legacy import LegacyMapStepBooster
+from .main import WorldMainMapCalculators
+from .partners import (
+    AmaneBelowExPartnerBonus,
+    AwakenedEtoPartnerBonus,
+    AwakenedIlithPartnerBonus,
+    AwakenedLunaPartnerBonus,
+    MayaPartnerBonus,
+    MithraTerceraPartnerBonus,
+)
+
+__all__ = [
+    "AmaneBelowExPartnerBonus",
+    "AwakenedEtoPartnerBonus",
+    "AwakenedIlithPartnerBonus",
+    "AwakenedLunaPartnerBonus",
+    "LegacyMapStepBooster",
+    "MayaPartnerBonus",
+    "MemoriesStepBooster",
+    "MithraTerceraPartnerBonus",
+    "PartnerBonus",
+    "WorldMainMapCalculators",
+    "WorldPlayResult",
+]

src/arcaea_offline/calculators/world/_common.py

@@ -0,0 +1,50 @@
+from decimal import Decimal
+from typing import Union
+
+
+class WorldPlayResult:
+    def __init__(
+        self,
+        *,
+        play_rating: Union[Decimal, str, float, int],
+        partner_step: Union[Decimal, str, float, int],
+    ):
+        self.__play_rating = play_rating
+        self.__partner_step = partner_step
+
+    @property
+    def play_rating(self):
+        return Decimal(self.__play_rating)
+
+    @property
+    def partner_step(self):
+        return Decimal(self.__partner_step)
+
+
+class PartnerBonus:
+    def __init__(
+        self,
+        *,
+        step_bonus: Union[Decimal, str, float, int] = Decimal("0.0"),
+        final_multiplier: Union[Decimal, str, float, int] = Decimal("1.0"),
+    ):
+        self.__step_bonus = step_bonus
+        self.__final_multiplier = final_multiplier
+
+    @property
+    def step_bonus(self):
+        return Decimal(self.__step_bonus)
+
+    @property
+    def final_multiplier(self):
+        return Decimal(self.__final_multiplier)
+
+
+class StepBooster:
+    def final_value(self) -> Decimal:
+        raise NotImplementedError()
+
+
+class MemoriesStepBooster(StepBooster):
+    def final_value(self) -> Decimal:
+        return Decimal("4.0")

src/arcaea_offline/calculators/world/legacy.py

@@ -0,0 +1,45 @@
+from decimal import Decimal
+from typing import Literal
+
+from ._common import StepBooster
+
+
+class LegacyMapStepBooster(StepBooster):
+    def __init__(
+        self,
+        stamina: Literal[2, 4, 6],
+        fragments: Literal[100, 250, 500, None],
+    ):
+        self.stamina = stamina
+        self.fragments = fragments
+
+    @property
+    def stamina(self):
+        return self.__stamina
+
+    @stamina.setter
+    def stamina(self, value: Literal[2, 4, 6]):
+        if value not in [2, 4, 6]:
+            raise ValueError("stamina can only be one of [2, 4, 6]")
+        self.__stamina = value
+
+    @property
+    def fragments(self):
+        return self.__fragments
+
+    @fragments.setter
+    def fragments(self, value: Literal[100, 250, 500, None]):
+        if value not in [100, 250, 500, None]:
+            raise ValueError("fragments can only be one of [100, 250, 500, None]")
+        self.__fragments = value
+
+    def final_value(self) -> Decimal:
+        stamina_multiplier = Decimal(self.stamina)
+        fragments_multiplier = Decimal(1)
+        if self.fragments == 100:
+            fragments_multiplier = Decimal("1.1")
+        elif self.fragments == 250:
+            fragments_multiplier = Decimal("1.25")
+        elif self.fragments == 500:
+            fragments_multiplier = Decimal("1.5")
+        return stamina_multiplier * fragments_multiplier

src/arcaea_offline/calculators/world/main.py

@@ -0,0 +1,57 @@
+from decimal import Decimal
+from typing import Optional, Union
+
+from ._common import PartnerBonus, StepBooster, WorldPlayResult
+
+
+class WorldMainMapCalculators:
+    @staticmethod
+    def step(
+        play_result: WorldPlayResult,
+        *,
+        partner_bonus: Optional[PartnerBonus] = None,
+        step_booster: Optional[StepBooster] = None,
+    ) -> Decimal:
+        ptt = play_result.play_rating
+        step = play_result.partner_step
+        if partner_bonus:
+            partner_bonus_step = partner_bonus.step_bonus
+            partner_bonus_multiplier = partner_bonus.final_multiplier
+        else:
+            partner_bonus_step = Decimal("0")
+            partner_bonus_multiplier = Decimal("1.0")
+
+        result = (Decimal("2.45") * ptt.sqrt() + Decimal("2.5")) * (step / 50)
+        result += partner_bonus_step
+        result *= partner_bonus_multiplier
+        if step_booster:
+            result *= step_booster.final_value()
+
+        return result
+
+    @staticmethod
+    def play_rating_from_step(
+        step: Union[Decimal, str, int, float],
+        partner_step_value: Union[Decimal, str, int, float],
+        *,
+        partner_bonus: Optional[PartnerBonus] = None,
+        step_booster: Optional[StepBooster] = None,
+    ):
+        step = Decimal(step)
+        partner_step_value = Decimal(partner_step_value)
+
+        # get original play result
+        if partner_bonus and partner_bonus.final_multiplier:
+            step /= partner_bonus.final_multiplier
+        if step_booster:
+            step /= step_booster.final_value()
+
+        if partner_bonus and partner_bonus.step_bonus:
+            step -= partner_bonus.step_bonus
+
+        play_rating_sqrt = (
+            Decimal(50) * step - Decimal("2.5") * partner_step_value
+        ) / (Decimal("2.45") * partner_step_value)
+        return (
+            play_rating_sqrt**2 if play_rating_sqrt >= 0 else -(play_rating_sqrt**2)
+        )

src/arcaea_offline/calculators/world/partners.py

@@ -0,0 +1,16 @@
+from ._common import PartnerBonus
+
+AwakenedIlithPartnerBonus = PartnerBonus(step_bonus="6.0")
+AwakenedEtoPartnerBonus = PartnerBonus(step_bonus="7.0")
+AwakenedLunaPartnerBonus = PartnerBonus(step_bonus="7.0")
+
+
+AmaneBelowExPartnerBonus = PartnerBonus(final_multiplier="0.5")
+
+
+class MithraTerceraPartnerBonus(PartnerBonus):
+    def __init__(self, step_bonus: int):
+        super().__init__(step_bonus=step_bonus)
+
+
+MayaPartnerBonus = PartnerBonus(final_multiplier="2.0")

src/arcaea_offline/constants/enums/__init__.py

@@ -0,0 +1,15 @@
+from .arcaea import (
+    ArcaeaLanguage,
+    ArcaeaPlayResultClearType,
+    ArcaeaPlayResultModifier,
+    ArcaeaRatingClass,
+    ArcaeaSongSide,
+)
+
+__all__ = [
+    "ArcaeaLanguage",
+    "ArcaeaPlayResultClearType",
+    "ArcaeaPlayResultModifier",
+    "ArcaeaRatingClass",
+    "ArcaeaSongSide",
+]

src/arcaea_offline/constants/enums/arcaea.py

@@ -0,0 +1,37 @@
+from enum import Enum, IntEnum
+
+
+class ArcaeaRatingClass(IntEnum):
+    PAST = 0
+    PRESENT = 1
+    FUTURE = 2
+    BEYOND = 3
+    ETERNAL = 4
+
+
+class ArcaeaSongSide(IntEnum):
+    LIGHT = 0
+    CONFLICT = 1
+    COLORLESS = 2
+
+
+class ArcaeaPlayResultModifier(IntEnum):
+    NORMAL = 0
+    EASY = 1
+    HARD = 2
+
+
+class ArcaeaPlayResultClearType(IntEnum):
+    TRACK_LOST = 0
+    NORMAL_CLEAR = 1
+    FULL_RECALL = 2
+    PURE_MEMORY = 3
+    HARD_CLEAR = 4
+    EASY_CLEAR = 5
+
+
+class ArcaeaLanguage(Enum):
+    JA = "ja"
+    KO = "ko"
+    ZH_HANT = "zh-Hant"
+    ZH_HANS = "zh-Hans"

src/arcaea_offline/constants/play_result.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ScoreLowerLimits:
+    EX_PLUS = 9900000
+    EX = 9800000
+    AA = 9500000
+    A = 9200000
+    B = 8900000
+    C = 8600000
+    D = 0

src/arcaea_offline/database.py

@@ -1,48 +0,0 @@
-from sqlalchemy import Engine, select
-from sqlalchemy.orm import sessionmaker
-
-from .models.config import *
-from .models.scores import *
-from .models.songs import *
-from .singleton import Singleton
-
-
-class Database(metaclass=Singleton):
-    def __init__(self, engine: Engine):
-        self.engine = engine
-
-    @property
-    def engine(self):
-        return self.__engine
-
-    @engine.setter
-    def engine(self, value: Engine):
-        if not isinstance(value, Engine):
-            raise ValueError("Database.engine only accepts sqlalchemy.Engine")
-        self.__engine = value
-        self.__sessionmaker = sessionmaker(self.__engine)
-
-    @property
-    def sessionmaker(self):
-        return self.__sessionmaker
-
-    def init(self, checkfirst: bool = True):
-        # create tables & views
-        if checkfirst:
-            # > https://github.com/kvesteri/sqlalchemy-utils/issues/396
-            # > view.create_view() causes DuplicateTableError on Base.metadata.create_all(checkfirst=True)
-            # so if `checkfirst` is True, drop these views before creating
-            ScoresViewBase.metadata.drop_all(self.engine)
-
-        SongsBase.metadata.create_all(self.engine, checkfirst=checkfirst)
-        ScoresBase.metadata.create_all(self.engine, checkfirst=checkfirst)
-        ScoresViewBase.metadata.create_all(self.engine)
-        ConfigBase.metadata.create_all(self.engine, checkfirst=checkfirst)
-
-        # insert version property
-        with self.sessionmaker() as session:
-            stmt = select(Property.value).where(Property.key == "version")
-            result = session.execute(stmt).fetchone()
-            if not checkfirst or not result:
-                session.add(Property(key="version", value="2"))
-                session.commit()

src/arcaea_offline/database/__init__.py

@@ -0,0 +1,3 @@
+from .db import Database
+
+__all__ = ["Database"]

src/arcaea_offline/database/db.py

@@ -0,0 +1,429 @@
+import logging
+import math
+from typing import Iterable, List, Optional, Type, Union
+
+from sqlalchemy import Engine, func, inspect, select
+from sqlalchemy.orm import DeclarativeBase, InstrumentedAttribute, sessionmaker
+
+from arcaea_offline.external.arcsong.arcsong_json import ArcSongJsonBuilder
+from arcaea_offline.external.exports import exporters
+from arcaea_offline.external.exports.types import ArcaeaOfflineDEFV2_Score, ScoreExport
+from arcaea_offline.singleton import Singleton
+
+from .models.v4.config import ConfigBase, Property
+from .models.v4.scores import (
+    CalculatedPotential,
+    Score,
+    ScoreBest,
+    ScoreCalculated,
+    ScoresBase,
+    ScoresViewBase,
+)
+from .models.v4.songs import (
+    Chart,
+    ChartInfo,
+    Difficulty,
+    DifficultyLocalized,
+    Pack,
+    PackLocalized,
+    Song,
+    SongLocalized,
+    SongsBase,
+    SongsViewBase,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Database(metaclass=Singleton):
+    def __init__(self, engine: Optional[Engine]):
+        try:
+            self.__engine
+        except AttributeError:
+            self.__engine = None
+
+        if engine is None:
+            if isinstance(self.engine, Engine):
+                return
+            raise ValueError("No sqlalchemy.Engine instance specified before.")
+
+        if not isinstance(engine, Engine):
+            raise ValueError(
+                f"A sqlalchemy.Engine instance expected, not {repr(engine)}"
+            )
+
+        if isinstance(self.engine, Engine):
+            logger.warning(
+                "A sqlalchemy.Engine instance %r has been specified "
+                "and will be replaced to %r",
+                self.engine,
+                engine,
+            )
+        self.engine = engine
+
+    @property
+    def engine(self) -> Engine:
+        return self.__engine  # type: ignore
+
+    @engine.setter
+    def engine(self, value: Engine):
+        if not isinstance(value, Engine):
+            raise ValueError("Database.engine only accepts sqlalchemy.Engine")
+        self.__engine = value
+        self.__sessionmaker = sessionmaker(self.__engine)
+
+    @property
+    def sessionmaker(self):
+        return self.__sessionmaker
+
+    # region init
+
+    def init(self, checkfirst: bool = True):
+        # create tables & views
+        if checkfirst:
+            # > https://github.com/kvesteri/sqlalchemy-utils/issues/396
+            # > view.create_view() causes DuplicateTableError on
+            # > Base.metadata.create_all(checkfirst=True)
+            # so if `checkfirst` is True, drop these views before creating
+            SongsViewBase.metadata.drop_all(self.engine)
+            ScoresViewBase.metadata.drop_all(self.engine)
+
+        SongsBase.metadata.create_all(self.engine, checkfirst=checkfirst)
+        SongsViewBase.metadata.create_all(self.engine)
+        ScoresBase.metadata.create_all(self.engine, checkfirst=checkfirst)
+        ScoresViewBase.metadata.create_all(self.engine)
+        ConfigBase.metadata.create_all(self.engine, checkfirst=checkfirst)
+
+        # insert version property
+        with self.sessionmaker() as session:
+            stmt = select(Property.value).where(Property.key == "version")
+            result = session.execute(stmt).fetchone()
+            if not checkfirst or not result:
+                session.add(Property(key="version", value="4"))
+                session.commit()
+
+    def check_init(self) -> bool:
+        # check table exists
+        expect_tables = (
+            list(SongsBase.metadata.tables.keys())
+            + list(ScoresBase.metadata.tables.keys())
+            + list(ConfigBase.metadata.tables.keys())
+            + [
+                Chart.__tablename__,
+                ScoreCalculated.__tablename__,
+                ScoreBest.__tablename__,
+                CalculatedPotential.__tablename__,
+            ]
+        )
+        return all(inspect(self.engine).has_table(t) for t in expect_tables)
+
+    # endregion
+
+    def version(self) -> Union[int, None]:
+        stmt = select(Property).where(Property.key == "version")
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return None if result is None else int(result.value)
+
+    # region Pack
+
+    def get_packs(self):
+        stmt = select(Pack)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_pack(self, pack_id: str):
+        stmt = select(Pack).where(Pack.id == pack_id)
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    def get_pack_localized(self, pack_id: str):
+        stmt = select(PackLocalized).where(PackLocalized.id == pack_id)
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    # endregion
+
+    # region Song
+
+    def get_songs(self):
+        stmt = select(Song)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_songs_by_pack_id(self, pack_id: str):
+        stmt = select(Song).where(Song.set == pack_id)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_song(self, song_id: str):
+        stmt = select(Song).where(Song.id == song_id)
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    def get_song_localized(self, song_id: str):
+        stmt = select(SongLocalized).where(SongLocalized.id == song_id)
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    # endregion
+
+    # region Difficulty
+
+    def get_difficulties(self):
+        stmt = select(Difficulty)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_difficulties_by_song_id(self, song_id: str):
+        stmt = select(Difficulty).where(Difficulty.song_id == song_id)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_difficulties_localized_by_song_id(self, song_id: str):
+        stmt = select(DifficultyLocalized).where(DifficultyLocalized.song_id == song_id)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_difficulty(self, song_id: str, rating_class: int):
+        stmt = select(Difficulty).where(
+            (Difficulty.song_id == song_id) & (Difficulty.rating_class == rating_class)
+        )
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    def get_difficulty_localized(self, song_id: str, rating_class: int):
+        stmt = select(DifficultyLocalized).where(
+            (DifficultyLocalized.song_id == song_id)
+            & (DifficultyLocalized.rating_class == rating_class)
+        )
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    # endregion
+
+    # region ChartInfo
+
+    def get_chart_infos(self):
+        stmt = select(ChartInfo)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_chart_infos_by_song_id(self, song_id: str):
+        stmt = select(ChartInfo).where(ChartInfo.song_id == song_id)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_chart_info(self, song_id: str, rating_class: int):
+        stmt = select(ChartInfo).where(
+            (ChartInfo.song_id == song_id) & (ChartInfo.rating_class == rating_class)
+        )
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    # endregion
+
+    # region Chart
+
+    def get_charts_by_pack_id(self, pack_id: str):
+        stmt = select(Chart).where(Chart.set == pack_id)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_charts_by_song_id(self, song_id: str):
+        stmt = select(Chart).where(Chart.song_id == song_id)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_charts_by_constant(self, constant: int):
+        stmt = select(Chart).where(Chart.constant == constant)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_chart(self, song_id: str, rating_class: int):
+        stmt = select(Chart).where(
+            (Chart.song_id == song_id) & (Chart.rating_class == rating_class)
+        )
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    # endregion
+
+    # region Score
+
+    def get_scores(self):
+        stmt = select(Score)
+        with self.sessionmaker() as session:
+            results = list(session.scalars(stmt))
+        return results
+
+    def get_score(self, score_id: int):
+        stmt = select(Score).where(Score.id == score_id)
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    def get_score_best(self, song_id: str, rating_class: int):
+        stmt = select(ScoreBest).where(
+            (ScoreBest.song_id == song_id) & (ScoreBest.rating_class == rating_class)
+        )
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    def insert_score(self, score: Score):
+        with self.sessionmaker() as session:
+            session.add(score)
+            session.commit()
+
+    def insert_scores(self, scores: Iterable[Score]):
+        with self.sessionmaker() as session:
+            session.add_all(scores)
+            session.commit()
+
+    def update_score(self, score: Score):
+        if score.id is None:
+            raise ValueError(
+                "Cannot determine which score to update, please specify `score.id`"
+            )
+        with self.sessionmaker() as session:
+            session.merge(score)
+            session.commit()
+
+    def delete_score(self, score: Score):
+        with self.sessionmaker() as session:
+            session.delete(score)
+            session.commit()
+
+    def recommend_charts(self, play_result: float, bounds: float = 0.1):
+        base_constant = math.ceil(play_result * 10)
+
+        results = []
+        results_id = []
+        with self.sessionmaker() as session:
+            for constant in range(base_constant - 20, base_constant + 1):
+                # from Pure Memory(EX+) to AA
+                score_modifier = (play_result * 10 - constant) / 10
+                if score_modifier >= 2.0:
+                    min_score = 10000000
+                elif score_modifier >= 1.0:
+                    min_score = 200000 * (score_modifier - 1) + 9800000
+                else:
+                    min_score = 300000 * score_modifier + 9500000
+                min_score = int(min_score)
+
+                charts = self.get_charts_by_constant(constant)
+                for chart in charts:
+                    score_best_stmt = select(ScoreBest).where(
+                        (ScoreBest.song_id == chart.song_id)
+                        & (ScoreBest.rating_class == chart.rating_class)
+                        & (ScoreBest.score >= min_score)
+                        & (play_result - bounds < ScoreBest.potential)
+                        & (ScoreBest.potential < play_result + bounds)
+                    )
+                    if session.scalar(score_best_stmt):
+                        chart_id = f"{chart.song_id},{chart.rating_class}"
+                        if chart_id not in results_id:
+                            results.append(chart)
+                            results_id.append(chart_id)
+
+        return results
+
+    # endregion
+
+    def get_b30(self):
+        stmt = select(CalculatedPotential.b30).select_from(CalculatedPotential)
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result
+
+    # region COUNT
+
+    def __count_table(self, base: Type[DeclarativeBase]):
+        stmt = select(func.count()).select_from(base)
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result or 0
+
+    def __count_column(self, column: InstrumentedAttribute):
+        stmt = select(func.count(column))
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result or 0
+
+    def count_packs(self):
+        return self.__count_column(Pack.id)
+
+    def count_songs(self):
+        return self.__count_column(Song.id)
+
+    def count_difficulties(self):
+        return self.__count_table(Difficulty)
+
+    def count_chart_infos(self):
+        return self.__count_table(ChartInfo)
+
+    def count_complete_chart_infos(self):
+        stmt = (
+            select(func.count())
+            .select_from(ChartInfo)
+            .where((ChartInfo.constant != None) & (ChartInfo.notes != None))
+        )
+        with self.sessionmaker() as session:
+            result = session.scalar(stmt)
+        return result or 0
+
+    def count_charts(self):
+        return self.__count_table(Chart)
+
+    def count_scores(self):
+        return self.__count_column(Score.id)
+
+    def count_scores_calculated(self):
+        return self.__count_table(ScoreCalculated)
+
+    def count_scores_best(self):
+        return self.__count_table(ScoreBest)
+
+    # endregion
+
+    # region export
+
+    def export_scores(self) -> List[ScoreExport]:
+        scores = self.get_scores()
+        return [exporters.score(score) for score in scores]
+
+    def export_scores_def_v2(self) -> ArcaeaOfflineDEFV2_Score:
+        scores = self.get_scores()
+        return {
+            "$schema": "https://arcaeaoffline.sevive.xyz/schemas/def/v2/score.schema.json",
+            "type": "score",
+            "version": 2,
+            "scores": [exporters.score_def_v2(score) for score in scores],
+        }
+
+    def generate_arcsong(self):
+        with self.sessionmaker() as session:
+            arcsong = ArcSongJsonBuilder(session).generate_arcsong_json()
+        return arcsong
+
+    # endregion

src/arcaea_offline/database/models/_custom_types.py

@@ -0,0 +1,46 @@
+from datetime import datetime, timezone
+from enum import IntEnum
+from typing import Optional, Type
+
+from sqlalchemy import DateTime, Integer
+from sqlalchemy.types import TypeDecorator
+
+
+class DbIntEnum(TypeDecorator):
+    """sqlalchemy `TypeDecorator` for `IntEnum`s"""
+
+    impl = Integer
+    cache_ok = True
+
+    def __init__(self, enum_class: Type[IntEnum]):
+        super().__init__()
+        self.enum_class = enum_class
+
+    def process_bind_param(self, value: Optional[IntEnum], dialect) -> Optional[int]:
+        return None if value is None else value.value
+
+    def process_result_value(self, value: Optional[int], dialect) -> Optional[IntEnum]:
+        return None if value is None else self.enum_class(value)
+
+
+class TZDateTime(TypeDecorator):
+    """
+    Store Timezone Aware Timestamps as Timezone Naive UTC
+
+    https://docs.sqlalchemy.org/en/20/core/custom_types.html#store-timezone-aware-timestamps-as-timezone-naive-utc
+    """
+
+    impl = DateTime
+    cache_ok = True
+
+    def process_bind_param(self, value: Optional[datetime], dialect):
+        if value is not None:
+            if not value.tzinfo or value.tzinfo.utcoffset(value) is None:
+                raise TypeError("tzinfo is required")
+            value = value.astimezone(timezone.utc).replace(tzinfo=None)
+        return value
+
+    def process_result_value(self, value: Optional[datetime], dialect):
+        if value is not None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value

src/arcaea_offline/database/models/v4/__init__.py

@@ -0,0 +1,42 @@
+from .config import ConfigBase, Property
+from .scores import (
+    CalculatedPotential,
+    Score,
+    ScoreBest,
+    ScoreCalculated,
+    ScoresBase,
+    ScoresViewBase,
+)
+from .songs import (
+    Chart,
+    ChartInfo,
+    Difficulty,
+    DifficultyLocalized,
+    Pack,
+    PackLocalized,
+    Song,
+    SongLocalized,
+    SongsBase,
+    SongsViewBase,
+)
+
+__all__ = [
+    "CalculatedPotential",
+    "Chart",
+    "ChartInfo",
+    "ConfigBase",
+    "Difficulty",
+    "DifficultyLocalized",
+    "Pack",
+    "PackLocalized",
+    "Property",
+    "Score",
+    "ScoreBest",
+    "ScoreCalculated",
+    "ScoresBase",
+    "ScoresViewBase",
+    "Song",
+    "SongLocalized",
+    "SongsBase",
+    "SongsViewBase",
+]

src/arcaea_offline/database/models/v4/common.py

@@ -1,8 +1,12 @@
+# pylint: disable=too-few-public-methods
+
 from sqlalchemy.orm import DeclarativeBase
 from sqlalchemy.orm.exc import DetachedInstanceError
 
 
 class ReprHelper:
+    # pylint: disable=no-member
+
     def _repr(self, **kwargs) -> str:
         """
         Helper for __repr__

src/arcaea_offline/database/models/v4/config.py

@@ -1,3 +1,5 @@
+# pylint: disable=too-few-public-methods
+
 from sqlalchemy import TEXT
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
@@ -14,7 +16,7 @@ class ConfigBase(DeclarativeBase, ReprHelper):
 
 
 class Property(ConfigBase):
-    __tablename__ = "property"
+    __tablename__ = "properties"
 
     key: Mapped[str] = mapped_column(TEXT(), primary_key=True)
     value: Mapped[str] = mapped_column(TEXT())

src/arcaea_offline/database/models/v4/scores.py

@@ -1,19 +1,21 @@
+# pylint: disable=too-few-public-methods, duplicate-code
+
 from typing import Optional
 
-from sqlalchemy import TEXT, case, func, inspect, select
+from sqlalchemy import TEXT, case, func, inspect, select, text
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 from sqlalchemy_utils import create_view
 
 from .common import ReprHelper
-from .songs import Chart, ChartInfo
+from .songs import ChartInfo, Difficulty
 
 __all__ = [
-    "ScoresBase",
-    "Score",
-    "ScoresViewBase",
-    "Calculated",
-    "Best",
     "CalculatedPotential",
+    "Score",
+    "ScoreBest",
+    "ScoreCalculated",
+    "ScoresBase",
+    "ScoresViewBase",
 ]
 
 
@@ -22,7 +24,7 @@ class ScoresBase(DeclarativeBase, ReprHelper):
 
 
 class Score(ScoresBase):
-    __tablename__ = "score"
+    __tablename__ = "scores"
 
     id: Mapped[int] = mapped_column(autoincrement=True, primary_key=True)
     song_id: Mapped[str] = mapped_column(TEXT())
@@ -33,9 +35,14 @@ class Score(ScoresBase):
     lost: Mapped[Optional[int]]
     date: Mapped[Optional[int]]
     max_recall: Mapped[Optional[int]]
-    r10_clear_type: Mapped[Optional[int]] = mapped_column(
-        comment="0: LOST, 1: COMPLETE, 2: HARD_LOST"
+    modifier: Mapped[Optional[int]] = mapped_column(
+        comment="0: NORMAL, 1: EASY, 2: HARD"
     )
+    clear_type: Mapped[Optional[int]] = mapped_column(
+        comment="0: TRACK LOST, 1: NORMAL CLEAR, 2: FULL RECALL, "
+        "3: PURE MEMORY, 4: EASY CLEAR, 5: HARD CLEAR"
+    )
+    comment: Mapped[Optional[str]] = mapped_column(TEXT())
 
 
 # How to create an SQL View with SQLAlchemy?
@@ -47,40 +54,56 @@ class ScoresViewBase(DeclarativeBase, ReprHelper):
     pass
 
 
-class Calculated(ScoresViewBase):
-    score_id: Mapped[str]
+class ScoreCalculated(ScoresViewBase):
+    __tablename__ = "scores_calculated"
+
+    id: Mapped[int]
     song_id: Mapped[str]
     rating_class: Mapped[int]
     score: Mapped[int]
     pure: Mapped[Optional[int]]
+    shiny_pure: Mapped[Optional[int]]
     far: Mapped[Optional[int]]
     lost: Mapped[Optional[int]]
     date: Mapped[Optional[int]]
     max_recall: Mapped[Optional[int]]
-    r10_clear_type: Mapped[Optional[int]]
-    shiny_pure: Mapped[Optional[int]]
+    modifier: Mapped[Optional[int]]
+    clear_type: Mapped[Optional[int]]
     potential: Mapped[float]
+    comment: Mapped[Optional[str]]
 
     __table__ = create_view(
-        name="calculated",
+        name=__tablename__,
         selectable=select(
-            Score.id.label("score_id"),
-            Chart.song_id,
-            Chart.rating_class,
+            Score.id,
+            Difficulty.song_id,
+            Difficulty.rating_class,
             Score.score,
             Score.pure,
+            (
+                case(
+                    (
+                        (
+                            ChartInfo.notes.is_not(None)
+                            & Score.pure.is_not(None)
+                            & Score.far.is_not(None)
+                            & (ChartInfo.notes != 0)
+                        ),
+                        Score.score
+                        - func.floor(
+                            (Score.pure * 10000000.0 / ChartInfo.notes)
+                            + (Score.far * 0.5 * 10000000.0 / ChartInfo.notes)
+                        ),
+                    ),
+                    else_=text("NULL"),
+                )
+            ).label("shiny_pure"),
             Score.far,
             Score.lost,
             Score.date,
             Score.max_recall,
-            Score.r10_clear_type,
-            (
-                Score.score
-                - func.floor(
-                    (Score.pure * 10000000.0 / ChartInfo.note)
-                    + (Score.far * 0.5 * 10000000.0 / ChartInfo.note)
-                )
-            ).label("shiny_pure"),
+            Score.modifier,
+            Score.clear_type,
             case(
                 (Score.score >= 10000000, ChartInfo.constant / 10.0 + 2),
                 (
@@ -92,62 +115,73 @@ class Calculated(ScoresViewBase):
                     0,
                 ),
             ).label("potential"),
+            Score.comment,
         )
-        .select_from(Chart)
+        .select_from(Difficulty)
         .join(
             ChartInfo,
-            (Chart.song_id == ChartInfo.song_id)
-            & (Chart.rating_class == ChartInfo.rating_class),
+            (Difficulty.song_id == ChartInfo.song_id)
+            & (Difficulty.rating_class == ChartInfo.rating_class),
         )
         .join(
             Score,
-            (Chart.song_id == Score.song_id)
-            & (Chart.rating_class == Score.rating_class),
+            (Difficulty.song_id == Score.song_id)
+            & (Difficulty.rating_class == Score.rating_class),
         ),
         metadata=ScoresViewBase.metadata,
         cascade_on_drop=False,
     )
 
 
-class Best(ScoresViewBase):
-    score_id: Mapped[str]
+class ScoreBest(ScoresViewBase):
+    __tablename__ = "scores_best"
+
+    id: Mapped[int]
     song_id: Mapped[str]
     rating_class: Mapped[int]
     score: Mapped[int]
     pure: Mapped[Optional[int]]
+    shiny_pure: Mapped[Optional[int]]
     far: Mapped[Optional[int]]
     lost: Mapped[Optional[int]]
     date: Mapped[Optional[int]]
     max_recall: Mapped[Optional[int]]
-    r10_clear_type: Mapped[Optional[int]]
-    shiny_pure: Mapped[Optional[int]]
+    modifier: Mapped[Optional[int]]
+    clear_type: Mapped[Optional[int]]
     potential: Mapped[float]
+    comment: Mapped[Optional[str]]
 
     __table__ = create_view(
-        name="best",
+        name=__tablename__,
         selectable=select(
-            *[col for col in inspect(Calculated).columns if col.name != "potential"],
-            func.max(Calculated.potential).label("potential"),
+            *[
+                col
+                for col in inspect(ScoreCalculated).columns
+                if col.name != "potential"
+            ],
+            func.max(ScoreCalculated.potential).label("potential"),
         )
-        .select_from(Calculated)
-        .group_by(Calculated.song_id, Calculated.rating_class)
-        .order_by(Calculated.potential.desc()),
+        .select_from(ScoreCalculated)
+        .group_by(ScoreCalculated.song_id, ScoreCalculated.rating_class)
+        .order_by(ScoreCalculated.potential.desc()),
         metadata=ScoresViewBase.metadata,
         cascade_on_drop=False,
     )
 
 
 class CalculatedPotential(ScoresViewBase):
+    __tablename__ = "calculated_potential"
+
     b30: Mapped[float]
 
     _select_bests_subquery = (
-        select(Best.potential.label("b30_sum"))
-        .order_by(Best.potential.desc())
+        select(ScoreBest.potential.label("b30_sum"))
+        .order_by(ScoreBest.potential.desc())
         .limit(30)
         .subquery()
     )
     __table__ = create_view(
-        name="calculated_potential",
+        name=__tablename__,
         selectable=select(func.avg(_select_bests_subquery.c.b30_sum).label("b30")),
         metadata=ScoresViewBase.metadata,
         cascade_on_drop=False,

src/arcaea_offline/database/models/v4/songs.py

@@ -1,19 +1,24 @@
+# pylint: disable=too-few-public-methods, duplicate-code
+
 from typing import Optional
 
-from sqlalchemy import TEXT, ForeignKey
+from sqlalchemy import TEXT, ForeignKey, func, select
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy_utils import create_view
 
 from .common import ReprHelper
 
 __all__ = [
-    "SongsBase",
+    "Chart",
+    "ChartInfo",
+    "Difficulty",
+    "DifficultyLocalized",
     "Pack",
     "PackLocalized",
     "Song",
     "SongLocalized",
-    "Chart",
-    "ChartLocalized",
-    "ChartInfo",
+    "SongsBase",
+    "SongsViewBase",
 ]
 
 
@@ -22,7 +27,7 @@ class SongsBase(DeclarativeBase, ReprHelper):
 
 
 class Pack(SongsBase):
-    __tablename__ = "pack"
+    __tablename__ = "packs"
 
     id: Mapped[str] = mapped_column(TEXT(), primary_key=True)
     name: Mapped[str] = mapped_column(TEXT())
@@ -30,9 +35,9 @@ class Pack(SongsBase):
 
 
 class PackLocalized(SongsBase):
-    __tablename__ = "pack_localized"
+    __tablename__ = "packs_localized"
 
-    id: Mapped[str] = mapped_column(ForeignKey("pack.id"), primary_key=True)
+    id: Mapped[str] = mapped_column(ForeignKey("packs.id"), primary_key=True)
     name_ja: Mapped[Optional[str]] = mapped_column(TEXT())
     name_ko: Mapped[Optional[str]] = mapped_column(TEXT())
     name_zh_hans: Mapped[Optional[str]] = mapped_column(TEXT())
@@ -44,7 +49,7 @@ class PackLocalized(SongsBase):
 
 
 class Song(SongsBase):
-    __tablename__ = "song"
+    __tablename__ = "songs"
 
     idx: Mapped[int]
     id: Mapped[str] = mapped_column(TEXT(), primary_key=True)
@@ -67,29 +72,41 @@ class Song(SongsBase):
 
 
 class SongLocalized(SongsBase):
-    __tablename__ = "song_localized"
+    __tablename__ = "songs_localized"
 
-    id: Mapped[str] = mapped_column(ForeignKey("song.id"), primary_key=True)
+    id: Mapped[str] = mapped_column(ForeignKey("songs.id"), primary_key=True)
     title_ja: Mapped[Optional[str]] = mapped_column(TEXT())
     title_ko: Mapped[Optional[str]] = mapped_column(TEXT())
     title_zh_hans: Mapped[Optional[str]] = mapped_column(TEXT())
     title_zh_hant: Mapped[Optional[str]] = mapped_column(TEXT())
-    search_title_ja: Mapped[Optional[str]] = mapped_column(TEXT(), comment="json")
-    search_title_ko: Mapped[Optional[str]] = mapped_column(TEXT(), comment="json")
-    search_title_zh_hans: Mapped[Optional[str]] = mapped_column(TEXT(), comment="json")
-    search_title_zh_hant: Mapped[Optional[str]] = mapped_column(TEXT(), comment="json")
-    search_artist_ja: Mapped[Optional[str]] = mapped_column(TEXT(), comment="json")
-    search_artist_ko: Mapped[Optional[str]] = mapped_column(TEXT(), comment="json")
-    search_artist_zh_hans: Mapped[Optional[str]] = mapped_column(TEXT(), comment="json")
-    search_artist_zh_hant: Mapped[Optional[str]] = mapped_column(TEXT(), comment="json")
+    search_title_ja: Mapped[Optional[str]] = mapped_column(TEXT(), comment="JSON array")
+    search_title_ko: Mapped[Optional[str]] = mapped_column(TEXT(), comment="JSON array")
+    search_title_zh_hans: Mapped[Optional[str]] = mapped_column(
+        TEXT(), comment="JSON array"
+    )
+    search_title_zh_hant: Mapped[Optional[str]] = mapped_column(
+        TEXT(), comment="JSON array"
+    )
+    search_artist_ja: Mapped[Optional[str]] = mapped_column(
+        TEXT(), comment="JSON array"
+    )
+    search_artist_ko: Mapped[Optional[str]] = mapped_column(
+        TEXT(), comment="JSON array"
+    )
+    search_artist_zh_hans: Mapped[Optional[str]] = mapped_column(
+        TEXT(), comment="JSON array"
+    )
+    search_artist_zh_hant: Mapped[Optional[str]] = mapped_column(
+        TEXT(), comment="JSON array"
+    )
     source_ja: Mapped[Optional[str]] = mapped_column(TEXT())
     source_ko: Mapped[Optional[str]] = mapped_column(TEXT())
     source_zh_hans: Mapped[Optional[str]] = mapped_column(TEXT())
     source_zh_hant: Mapped[Optional[str]] = mapped_column(TEXT())
 
 
-class Chart(SongsBase):
-    __tablename__ = "chart"
+class Difficulty(SongsBase):
+    __tablename__ = "difficulties"
 
     song_id: Mapped[str] = mapped_column(TEXT(), primary_key=True)
     rating_class: Mapped[int] = mapped_column(primary_key=True)
@@ -110,12 +127,14 @@ class Chart(SongsBase):
     date: Mapped[Optional[int]]
 
 
-class ChartLocalized(SongsBase):
-    __tablename__ = "chart_localized"
+class DifficultyLocalized(SongsBase):
+    __tablename__ = "difficulties_localized"
 
-    song_id: Mapped[str] = mapped_column(ForeignKey("chart.song_id"), primary_key=True)
+    song_id: Mapped[str] = mapped_column(
+        ForeignKey("difficulties.song_id"), primary_key=True
+    )
     rating_class: Mapped[str] = mapped_column(
-        ForeignKey("chart.rating_class"), primary_key=True
+        ForeignKey("difficulties.rating_class"), primary_key=True
     )
     title_ja: Mapped[Optional[str]] = mapped_column(TEXT())
     title_ko: Mapped[Optional[str]] = mapped_column(TEXT())
@@ -128,13 +147,95 @@ class ChartLocalized(SongsBase):
 
 
 class ChartInfo(SongsBase):
-    __tablename__ = "chart_info"
+    __tablename__ = "charts_info"
 
-    song_id: Mapped[str] = mapped_column(ForeignKey("chart.song_id"), primary_key=True)
+    song_id: Mapped[str] = mapped_column(
+        ForeignKey("difficulties.song_id"), primary_key=True
+    )
     rating_class: Mapped[str] = mapped_column(
-        ForeignKey("chart.rating_class"), primary_key=True
+        ForeignKey("difficulties.rating_class"), primary_key=True
     )
     constant: Mapped[int] = mapped_column(
-        comment="real_constant * 10. For example, Crimson Throne [FTR] is 10.4, then store 104 here."
+        comment="real_constant * 10. For example, Crimson Throne [FTR] is 10.4, then store 104."
+    )
+    notes: Mapped[Optional[int]]
+
+
+class SongsViewBase(DeclarativeBase, ReprHelper):
+    pass
+
+
+class Chart(SongsViewBase):
+    __tablename__ = "charts"
+
+    song_idx: Mapped[int]
+    song_id: Mapped[str]
+    rating_class: Mapped[int]
+    rating: Mapped[int]
+    rating_plus: Mapped[bool]
+    title: Mapped[str]
+    artist: Mapped[str]
+    set: Mapped[str]
+    bpm: Mapped[Optional[str]]
+    bpm_base: Mapped[Optional[float]]
+    audio_preview: Mapped[Optional[int]]
+    audio_preview_end: Mapped[Optional[int]]
+    side: Mapped[Optional[int]]
+    version: Mapped[Optional[str]]
+    date: Mapped[Optional[int]]
+    bg: Mapped[Optional[str]]
+    bg_inverse: Mapped[Optional[str]]
+    bg_day: Mapped[Optional[str]]
+    bg_night: Mapped[Optional[str]]
+    source: Mapped[Optional[str]]
+    source_copyright: Mapped[Optional[str]]
+    chart_designer: Mapped[Optional[str]]
+    jacket_desginer: Mapped[Optional[str]]
+    audio_override: Mapped[bool]
+    jacket_override: Mapped[bool]
+    jacket_night: Mapped[Optional[str]]
+    constant: Mapped[int]
+    notes: Mapped[Optional[int]]
+
+    __table__ = create_view(
+        name=__tablename__,
+        selectable=select(
+            Song.idx.label("song_idx"),
+            Difficulty.song_id,
+            Difficulty.rating_class,
+            Difficulty.rating,
+            Difficulty.rating_plus,
+            func.coalesce(Difficulty.title, Song.title).label("title"),
+            func.coalesce(Difficulty.artist, Song.artist).label("artist"),
+            Song.set,
+            func.coalesce(Difficulty.bpm, Song.bpm).label("bpm"),
+            func.coalesce(Difficulty.bpm_base, Song.bpm_base).label("bpm_base"),
+            Song.audio_preview,
+            Song.audio_preview_end,
+            Song.side,
+            func.coalesce(Difficulty.version, Song.version).label("version"),
+            func.coalesce(Difficulty.date, Song.date).label("date"),
+            func.coalesce(Difficulty.bg, Song.bg).label("bg"),
+            func.coalesce(Difficulty.bg_inverse, Song.bg_inverse).label("bg_inverse"),
+            Song.bg_day,
+            Song.bg_night,
+            Song.source,
+            Song.source_copyright,
+            Difficulty.chart_designer,
+            Difficulty.jacket_desginer,
+            Difficulty.audio_override,
+            Difficulty.jacket_override,
+            Difficulty.jacket_night,
+            ChartInfo.constant,
+            ChartInfo.notes,
+        )
+        .select_from(Difficulty)
+        .join(
+            ChartInfo,
+            (Difficulty.song_id == ChartInfo.song_id)
+            & (Difficulty.rating_class == ChartInfo.rating_class),
+        )
+        .join(Song, Difficulty.song_id == Song.id),
+        metadata=SongsViewBase.metadata,
+        cascade_on_drop=False,
     )
-    note: Mapped[Optional[int]]

src/arcaea_offline/database/models/v5/__init__.py

@@ -0,0 +1,38 @@
+from .arcaea import (
+    Chart,
+    ChartInfo,
+    Difficulty,
+    DifficultyLocalized,
+    Pack,
+    PackLocalized,
+    Song,
+    SongLocalized,
+    SongSearchWord,
+)
+from .base import ModelsV5Base, ModelsV5ViewBase
+from .config import Property
+from .play_results import (
+    CalculatedPotential,
+    PlayResult,
+    PlayResultBest,
+    PlayResultCalculated,
+)
+
+__all__ = [
+    "CalculatedPotential",
+    "Chart",
+    "ChartInfo",
+    "Difficulty",
+    "DifficultyLocalized",
+    "ModelsV5Base",
+    "ModelsV5ViewBase",
+    "Pack",
+    "PackLocalized",
+    "PlayResult",
+    "PlayResultBest",
+    "PlayResultCalculated",
+    "Property",
+    "Song",
+    "SongLocalized",
+    "SongSearchWord",
+]

src/arcaea_offline/database/models/v5/arcaea.py

@@ -0,0 +1,275 @@
+from typing import List, Optional
+
+from sqlalchemy import ForeignKey, and_, func, select
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy_utils import create_view
+
+from arcaea_offline.constants.enums import ArcaeaRatingClass, ArcaeaSongSide
+
+from .base import ModelsV5Base, ModelsV5ViewBase, ReprHelper
+
+__all__ = [
+    "Chart",
+    "ChartInfo",
+    "Difficulty",
+    "DifficultyLocalized",
+    "Pack",
+    "PackLocalized",
+    "Song",
+    "SongLocalized",
+]
+
+
+class Pack(ModelsV5Base, ReprHelper):
+    __tablename__ = "packs"
+
+    id: Mapped[str] = mapped_column(primary_key=True)
+    name: Mapped[str]
+    description: Mapped[Optional[str]]
+
+    songs: Mapped[List["Song"]] = relationship(back_populates="pack", viewonly=True)
+    localized_objects: Mapped[List["PackLocalized"]] = relationship(
+        back_populates="parent", viewonly=True
+    )
+
+
+class PackLocalized(ModelsV5Base, ReprHelper):
+    __tablename__ = "packs_localized"
+
+    pkid: Mapped[int] = mapped_column(primary_key=True)
+    id: Mapped[str] = mapped_column(
+        ForeignKey(Pack.id, onupdate="CASCADE", ondelete="NO ACTION")
+    )
+    lang: Mapped[str]
+    name: Mapped[Optional[str]]
+    description: Mapped[Optional[str]]
+
+    parent: Mapped[Pack] = relationship(viewonly=True)
+
+
+class Song(ModelsV5Base, ReprHelper):
+    __tablename__ = "songs"
+
+    idx: Mapped[int]
+    id: Mapped[str] = mapped_column(primary_key=True)
+    title: Mapped[str]
+    artist: Mapped[str]
+    pack_id: Mapped[str] = mapped_column(
+        ForeignKey(Pack.id, onupdate="CASCADE", ondelete="NO ACTION")
+    )
+    bpm: Mapped[Optional[str]]
+    bpm_base: Mapped[Optional[float]]
+    audio_preview: Mapped[Optional[int]]
+    audio_preview_end: Mapped[Optional[int]]
+    side: Mapped[Optional[ArcaeaSongSide]]
+    version: Mapped[Optional[str]]
+    date: Mapped[Optional[int]]
+    bg: Mapped[Optional[str]]
+    bg_inverse: Mapped[Optional[str]]
+    bg_day: Mapped[Optional[str]]
+    bg_night: Mapped[Optional[str]]
+    source: Mapped[Optional[str]]
+    source_copyright: Mapped[Optional[str]]
+
+    pack: Mapped[Pack] = relationship(viewonly=True)
+    difficulties: Mapped[List["Difficulty"]] = relationship(
+        back_populates="song", viewonly=True
+    )
+    localized_objects: Mapped[List["SongLocalized"]] = relationship(
+        back_populates="parent", viewonly=True
+    )
+
+    @property
+    def charts_info(self):
+        return [d.chart_info for d in self.difficulties if d.chart_info is not None]
+
+
+class SongLocalized(ModelsV5Base, ReprHelper):
+    __tablename__ = "songs_localized"
+
+    pkid: Mapped[int] = mapped_column(primary_key=True)
+    id: Mapped[str] = mapped_column(
+        ForeignKey(Song.id, onupdate="CASCADE", ondelete="NO ACTION")
+    )
+    lang: Mapped[str]
+    title: Mapped[Optional[str]]
+    source: Mapped[Optional[str]]
+
+    parent: Mapped[Song] = relationship(
+        back_populates="localized_objects", viewonly=True
+    )
+
+
+class SongSearchWord(ModelsV5Base, ReprHelper):
+    __tablename__ = "songs_search_words"
+
+    pkid: Mapped[int] = mapped_column(primary_key=True)
+    id: Mapped[str] = mapped_column(
+        ForeignKey(Song.id, onupdate="CASCADE", ondelete="NO ACTION")
+    )
+    lang: Mapped[str]
+    type: Mapped[int] = mapped_column(comment="1: title, 2: artist")
+    value: Mapped[str]
+
+
+class Difficulty(ModelsV5Base, ReprHelper):
+    __tablename__ = "difficulties"
+
+    song_id: Mapped[str] = mapped_column(
+        ForeignKey(Song.id, onupdate="CASCADE", ondelete="NO ACTION"),
+        primary_key=True,
+    )
+    rating_class: Mapped[ArcaeaRatingClass] = mapped_column(primary_key=True)
+    rating: Mapped[int]
+    rating_plus: Mapped[bool]
+    chart_designer: Mapped[Optional[str]]
+    jacket_desginer: Mapped[Optional[str]]
+    audio_override: Mapped[bool] = mapped_column(default=False)
+    jacket_override: Mapped[bool] = mapped_column(default=False)
+    jacket_night: Mapped[Optional[str]]
+    title: Mapped[Optional[str]]
+    artist: Mapped[Optional[str]]
+    bg: Mapped[Optional[str]]
+    bg_inverse: Mapped[Optional[str]]
+    bpm: Mapped[Optional[str]]
+    bpm_base: Mapped[Optional[float]]
+    version: Mapped[Optional[str]]
+    date: Mapped[Optional[int]]
+
+    song: Mapped[Song] = relationship(back_populates="difficulties", viewonly=True)
+    chart_info: Mapped[Optional["ChartInfo"]] = relationship(
+        primaryjoin=(
+            "and_(Difficulty.song_id==ChartInfo.song_id, "
+            "Difficulty.rating_class==ChartInfo.rating_class)"
+        ),
+        viewonly=True,
+    )
+    localized_objects: Mapped[List["DifficultyLocalized"]] = relationship(
+        primaryjoin=(
+            "and_(Difficulty.song_id==DifficultyLocalized.song_id, "
+            "Difficulty.rating_class==DifficultyLocalized.rating_class)"
+        ),
+        viewonly=True,
+    )
+
+
+class DifficultyLocalized(ModelsV5Base, ReprHelper):
+    __tablename__ = "difficulties_localized"
+
+    pkid: Mapped[int] = mapped_column(primary_key=True)
+    song_id: Mapped[str] = mapped_column(
+        ForeignKey(Difficulty.song_id, onupdate="CASCADE", ondelete="NO ACTION")
+    )
+    rating_class: Mapped[ArcaeaRatingClass] = mapped_column(
+        ForeignKey(Difficulty.rating_class, onupdate="CASCADE", ondelete="NO ACTION")
+    )
+    lang: Mapped[str]
+    title: Mapped[Optional[str]]
+    artist: Mapped[Optional[str]]
+
+    parent: Mapped[Difficulty] = relationship(
+        primaryjoin=and_(
+            Difficulty.song_id == song_id, Difficulty.rating_class == rating_class
+        ),
+        viewonly=True,
+    )
+
+
+class ChartInfo(ModelsV5Base, ReprHelper):
+    __tablename__ = "charts_info"
+
+    song_id: Mapped[str] = mapped_column(
+        ForeignKey(Difficulty.song_id, onupdate="CASCADE", ondelete="NO ACTION"),
+        primary_key=True,
+    )
+    rating_class: Mapped[ArcaeaRatingClass] = mapped_column(
+        ForeignKey(Difficulty.rating_class, onupdate="CASCADE", ondelete="NO ACTION"),
+        primary_key=True,
+    )
+    constant: Mapped[int] = mapped_column(
+        comment="real_constant * 10. For example, Crimson Throne [FTR] is 10.4, then store 104."
+    )
+    notes: Mapped[Optional[int]]
+
+    difficulty: Mapped[Difficulty] = relationship(
+        primaryjoin=and_(
+            Difficulty.song_id == song_id, Difficulty.rating_class == rating_class
+        ),
+        viewonly=True,
+    )
+
+
+class Chart(ModelsV5ViewBase, ReprHelper):
+    __tablename__ = "charts"
+
+    song_idx: Mapped[int]
+    song_id: Mapped[str]
+    rating_class: Mapped[ArcaeaRatingClass]
+    rating: Mapped[int]
+    rating_plus: Mapped[bool]
+    title: Mapped[str]
+    artist: Mapped[str]
+    pack_id: Mapped[str]
+    bpm: Mapped[Optional[str]]
+    bpm_base: Mapped[Optional[float]]
+    audio_preview: Mapped[Optional[int]]
+    audio_preview_end: Mapped[Optional[int]]
+    side: Mapped[Optional[int]]
+    version: Mapped[Optional[str]]
+    date: Mapped[Optional[int]]
+    bg: Mapped[Optional[str]]
+    bg_inverse: Mapped[Optional[str]]
+    bg_day: Mapped[Optional[str]]
+    bg_night: Mapped[Optional[str]]
+    source: Mapped[Optional[str]]
+    source_copyright: Mapped[Optional[str]]
+    chart_designer: Mapped[Optional[str]]
+    jacket_desginer: Mapped[Optional[str]]
+    audio_override: Mapped[bool]
+    jacket_override: Mapped[bool]
+    jacket_night: Mapped[Optional[str]]
+    constant: Mapped[int]
+    notes: Mapped[Optional[int]]
+
+    __table__ = create_view(
+        name=__tablename__,
+        selectable=select(
+            Song.idx.label("song_idx"),
+            Difficulty.song_id,
+            Difficulty.rating_class,
+            Difficulty.rating,
+            Difficulty.rating_plus,
+            func.coalesce(Difficulty.title, Song.title).label("title"),
+            func.coalesce(Difficulty.artist, Song.artist).label("artist"),
+            Song.pack_id,
+            func.coalesce(Difficulty.bpm, Song.bpm).label("bpm"),
+            func.coalesce(Difficulty.bpm_base, Song.bpm_base).label("bpm_base"),
+            Song.audio_preview,
+            Song.audio_preview_end,
+            Song.side,
+            func.coalesce(Difficulty.version, Song.version).label("version"),
+            func.coalesce(Difficulty.date, Song.date).label("date"),
+            func.coalesce(Difficulty.bg, Song.bg).label("bg"),
+            func.coalesce(Difficulty.bg_inverse, Song.bg_inverse).label("bg_inverse"),
+            Song.bg_day,
+            Song.bg_night,
+            Song.source,
+            Song.source_copyright,
+            Difficulty.chart_designer,
+            Difficulty.jacket_desginer,
+            Difficulty.audio_override,
+            Difficulty.jacket_override,
+            Difficulty.jacket_night,
+            ChartInfo.constant,
+            ChartInfo.notes,
+        )
+        .select_from(Difficulty)
+        .join(
+            ChartInfo,
+            (Difficulty.song_id == ChartInfo.song_id)
+            & (Difficulty.rating_class == ChartInfo.rating_class),
+        )
+        .join(Song, Difficulty.song_id == Song.id),
+        metadata=ModelsV5ViewBase.metadata,
+        cascade_on_drop=False,
+    )

src/arcaea_offline/database/models/v5/base.py

@@ -0,0 +1,62 @@
+from datetime import datetime
+
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm.exc import DetachedInstanceError
+
+from arcaea_offline.constants.enums import (
+    ArcaeaPlayResultClearType,
+    ArcaeaPlayResultModifier,
+    ArcaeaRatingClass,
+    ArcaeaSongSide,
+)
+
+from .._custom_types import DbIntEnum, TZDateTime
+
+TYPE_ANNOTATION_MAP = {
+    datetime: TZDateTime,
+    ArcaeaRatingClass: DbIntEnum(ArcaeaRatingClass),
+    ArcaeaSongSide: DbIntEnum(ArcaeaSongSide),
+    ArcaeaPlayResultClearType: DbIntEnum(ArcaeaPlayResultClearType),
+    ArcaeaPlayResultModifier: DbIntEnum(ArcaeaPlayResultModifier),
+}
+
+
+class ModelsV5Base(DeclarativeBase):
+    type_annotation_map = TYPE_ANNOTATION_MAP
+
+
+class ModelsV5ViewBase(DeclarativeBase):
+    type_annotation_map = TYPE_ANNOTATION_MAP
+
+
+class ReprHelper:
+    # pylint: disable=no-member
+
+    def _repr(self, **kwargs) -> str:
+        """
+        Helper for __repr__
+
+        https://stackoverflow.com/a/55749579/16484891
+
+        CC BY-SA 4.0
+        """
+        field_strings = []
+        at_least_one_attached_attribute = False
+        for key, field in kwargs.items():
+            try:
+                field_strings.append(f"{key}={field!r}")
+            except DetachedInstanceError:
+                field_strings.append(f"{key}=DetachedInstanceError")
+            else:
+                at_least_one_attached_attribute = True
+
+        if at_least_one_attached_attribute:
+            return f"<{self.__class__.__name__}({', '.join(field_strings)})>"
+        return f"<{self.__class__.__name__} {id(self)}>"
+
+    def __repr__(self):
+        if isinstance(self, DeclarativeBase):
+            return self._repr(
+                **{c.key: getattr(self, c.key) for c in self.__table__.columns}
+            )
+        return super().__repr__()

src/arcaea_offline/database/models/v5/config.py

@@ -0,0 +1,12 @@
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import ModelsV5Base, ReprHelper
+
+__all__ = ["Property"]
+
+
+class Property(ModelsV5Base, ReprHelper):
+    __tablename__ = "properties"
+
+    key: Mapped[str] = mapped_column(primary_key=True)
+    value: Mapped[str] = mapped_column()

src/arcaea_offline/database/models/v5/play_results.py

@@ -0,0 +1,197 @@
+from datetime import datetime, timezone
+from typing import Optional
+
+from sqlalchemy import ForeignKey, and_, case, func, inspect, select, text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy_utils import create_view
+
+from arcaea_offline.constants.enums import (
+    ArcaeaPlayResultClearType,
+    ArcaeaPlayResultModifier,
+    ArcaeaRatingClass,
+)
+
+from .arcaea import ChartInfo, Difficulty
+from .base import ModelsV5Base, ModelsV5ViewBase, ReprHelper
+
+__all__ = [
+    "CalculatedPotential",
+    "PlayResult",
+    "PlayResultBest",
+    "PlayResultCalculated",
+]
+
+
+class PlayResult(ModelsV5Base, ReprHelper):
+    __tablename__ = "play_results"
+
+    id: Mapped[int] = mapped_column(autoincrement=True, primary_key=True)
+    song_id: Mapped[str] = mapped_column(
+        ForeignKey(Difficulty.song_id, onupdate="CASCADE", ondelete="NO ACTION"),
+        index=True,
+    )
+    rating_class: Mapped[ArcaeaRatingClass] = mapped_column(
+        ForeignKey(Difficulty.rating_class, onupdate="CASCADE", ondelete="NO ACTION"),
+        index=True,
+    )
+    score: Mapped[int]
+    pure: Mapped[Optional[int]]
+    far: Mapped[Optional[int]]
+    lost: Mapped[Optional[int]]
+    date: Mapped[Optional[datetime]] = mapped_column(
+        default=lambda: datetime.now(timezone.utc)
+    )
+    max_recall: Mapped[Optional[int]]
+    modifier: Mapped[Optional[ArcaeaPlayResultModifier]]
+    clear_type: Mapped[Optional[ArcaeaPlayResultClearType]]
+    comment: Mapped[Optional[str]]
+
+    difficulty: Mapped[Difficulty] = relationship(
+        primaryjoin=and_(
+            song_id == Difficulty.song_id,
+            rating_class == Difficulty.rating_class,
+        ),
+        viewonly=True,
+    )
+
+
+# How to create an SQL View with SQLAlchemy?
+# https://stackoverflow.com/a/53253105/16484891
+# CC BY-SA 4.0
+
+
+class PlayResultCalculated(ModelsV5ViewBase, ReprHelper):
+    __tablename__ = "play_results_calculated"
+
+    id: Mapped[int]
+    song_id: Mapped[str]
+    rating_class: Mapped[ArcaeaRatingClass]
+    score: Mapped[int]
+    pure: Mapped[Optional[int]]
+    shiny_pure: Mapped[Optional[int]]
+    far: Mapped[Optional[int]]
+    lost: Mapped[Optional[int]]
+    date: Mapped[Optional[datetime]]
+    max_recall: Mapped[Optional[int]]
+    modifier: Mapped[Optional[ArcaeaPlayResultModifier]]
+    clear_type: Mapped[Optional[ArcaeaPlayResultClearType]]
+    potential: Mapped[float]
+    comment: Mapped[Optional[str]]
+
+    __table__ = create_view(
+        name=__tablename__,
+        selectable=select(
+            PlayResult.id,
+            Difficulty.song_id,
+            Difficulty.rating_class,
+            PlayResult.score,
+            PlayResult.pure,
+            (
+                case(
+                    (
+                        (
+                            ChartInfo.notes.is_not(None)
+                            & PlayResult.pure.is_not(None)
+                            & PlayResult.far.is_not(None)
+                            & (ChartInfo.notes != 0)
+                        ),
+                        PlayResult.score
+                        - func.floor(
+                            (PlayResult.pure * 10000000.0 / ChartInfo.notes)
+                            + (PlayResult.far * 0.5 * 10000000.0 / ChartInfo.notes)
+                        ),
+                    ),
+                    else_=text("NULL"),
+                )
+            ).label("shiny_pure"),
+            PlayResult.far,
+            PlayResult.lost,
+            PlayResult.date,
+            PlayResult.max_recall,
+            PlayResult.modifier,
+            PlayResult.clear_type,
+            case(
+                (PlayResult.score >= 10000000, ChartInfo.constant / 10.0 + 2),  # noqa: PLR2004
+                (
+                    PlayResult.score >= 9800000,  # noqa: PLR2004
+                    ChartInfo.constant / 10.0
+                    + 1
+                    + (PlayResult.score - 9800000) / 200000.0,
+                ),
+                else_=func.max(
+                    (ChartInfo.constant / 10.0)
+                    + (PlayResult.score - 9500000) / 300000.0,
+                    0,
+                ),
+            ).label("potential"),
+            PlayResult.comment,
+        )
+        .select_from(Difficulty)
+        .join(
+            ChartInfo,
+            (Difficulty.song_id == ChartInfo.song_id)
+            & (Difficulty.rating_class == ChartInfo.rating_class),
+        )
+        .join(
+            PlayResult,
+            (Difficulty.song_id == PlayResult.song_id)
+            & (Difficulty.rating_class == PlayResult.rating_class),
+        ),
+        metadata=ModelsV5ViewBase.metadata,
+        cascade_on_drop=False,
+    )
+
+
+class PlayResultBest(ModelsV5ViewBase, ReprHelper):
+    __tablename__ = "play_results_best"
+
+    id: Mapped[int]
+    song_id: Mapped[str]
+    rating_class: Mapped[int]
+    score: Mapped[int]
+    pure: Mapped[Optional[int]]
+    shiny_pure: Mapped[Optional[int]]
+    far: Mapped[Optional[int]]
+    lost: Mapped[Optional[int]]
+    date: Mapped[Optional[datetime]]
+    max_recall: Mapped[Optional[int]]
+    modifier: Mapped[Optional[ArcaeaPlayResultModifier]]
+    clear_type: Mapped[Optional[ArcaeaPlayResultClearType]]
+    potential: Mapped[float]
+    comment: Mapped[Optional[str]]
+
+    __table__ = create_view(
+        name=__tablename__,
+        selectable=select(
+            *[
+                col
+                for col in inspect(PlayResultCalculated).columns
+                if col.name != "potential"
+            ],
+            func.max(PlayResultCalculated.potential).label("potential"),
+        )
+        .select_from(PlayResultCalculated)
+        .group_by(PlayResultCalculated.song_id, PlayResultCalculated.rating_class)
+        .order_by(PlayResultCalculated.potential.desc()),
+        metadata=ModelsV5ViewBase.metadata,
+        cascade_on_drop=False,
+    )
+
+
+class CalculatedPotential(ModelsV5ViewBase, ReprHelper):
+    __tablename__ = "calculated_potential"
+
+    b30: Mapped[float]
+
+    _select_bests_subquery = (
+        select(PlayResultBest.potential.label("b30_sum"))
+        .order_by(PlayResultBest.potential.desc())
+        .limit(30)
+        .subquery()
+    )
+    __table__ = create_view(
+        name=__tablename__,
+        selectable=select(func.avg(_select_bests_subquery.c.b30_sum).label("b30")),
+        metadata=ModelsV5ViewBase.metadata,
+        cascade_on_drop=False,
+    )

src/arcaea_offline/external/andreal/__init__.py

@@ -0,0 +1,3 @@
+from .api_data import AndrealImageGeneratorApiDataConverter
+
+__all__ = ["AndrealImageGeneratorApiDataConverter"]

src/arcaea_offline/external/andreal/account.py

@@ -0,0 +1,14 @@
+class AndrealImageGeneratorAccount:
+    def __init__(
+        self,
+        name: str = "Player",
+        code: int = 123456789,
+        rating: int = -1,
+        character: int = 5,
+        character_uncapped: bool = False,
+    ):
+        self.name = name
+        self.code = code
+        self.rating = rating
+        self.character = character
+        self.character_uncapped = character_uncapped

src/arcaea_offline/external/andreal/api_data.py

@@ -0,0 +1,98 @@
+from typing import Optional, Union
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from ...models import CalculatedPotential, ScoreBest, ScoreCalculated
+from .account import AndrealImageGeneratorAccount
+
+
+class AndrealImageGeneratorApiDataConverter:
+    def __init__(
+        self,
+        session: Session,
+        account: AndrealImageGeneratorAccount = AndrealImageGeneratorAccount(),
+    ):
+        self.session = session
+        self.account = account
+
+    def account_info(self):
+        return {
+            "code": self.account.code,
+            "name": self.account.name,
+            "is_char_uncapped": self.account.character_uncapped,
+            "rating": self.account.rating,
+            "character": self.account.character,
+        }
+
+    def score(self, score: Union[ScoreCalculated, ScoreBest]):
+        return {
+            "score": score.score,
+            "health": 75,
+            "rating": score.potential,
+            "song_id": score.song_id,
+            "modifier": score.modifier or 0,
+            "difficulty": score.rating_class,
+            "clear_type": score.clear_type or 1,
+            "best_clear_type": score.clear_type or 1,
+            "time_played": score.date * 1000 if score.date else 0,
+            "near_count": score.far,
+            "miss_count": score.lost,
+            "perfect_count": score.pure,
+            "shiny_perfect_count": score.shiny_pure,
+        }
+
+    def user_info(self, score: Optional[ScoreCalculated] = None):
+        if not score:
+            score = self.session.scalar(
+                select(ScoreCalculated).order_by(ScoreCalculated.date.desc()).limit(1)
+            )
+        if not score:
+            raise ValueError("No score available.")
+
+        return {
+            "content": {
+                "account_info": self.account_info(),
+                "recent_score": [self.score(score)],
+            }
+        }
+
+    def user_best(self, song_id: str, rating_class: int):
+        score = self.session.scalar(
+            select(ScoreBest).where(
+                (ScoreBest.song_id == song_id)
+                & (ScoreBest.rating_class == rating_class)
+            )
+        )
+        if not score:
+            raise ValueError("No score available.")
+
+        return {
+            "content": {
+                "account_info": self.account_info(),
+                "record": self.score(score),
+            }
+        }
+
+    def user_best30(self):
+        scores = list(
+            self.session.scalars(
+                select(ScoreBest).order_by(ScoreBest.potential.desc()).limit(40)
+            )
+        )
+        if not scores:
+            raise ValueError("No score available.")
+        best30_avg = self.session.scalar(select(CalculatedPotential.b30))
+
+        best30_overflow = (
+            [self.score(score) for score in scores[30:40]] if len(scores) > 30 else []
+        )
+
+        return {
+            "content": {
+                "account_info": self.account_info(),
+                "best30_avg": best30_avg,
+                "best30_list": [self.score(score) for score in scores[:30]],
+                "best30_overflow": best30_overflow,
+            }
+        }

src/arcaea_offline/external/arcaea/__init__.py

@@ -1,3 +1,12 @@
+from .online import ArcaeaOnlineParser
 from .packlist import PacklistParser
 from .songlist import SonglistDifficultiesParser, SonglistParser
 from .st3 import St3ScoreParser
+
+__all__ = [
+    "ArcaeaOnlineParser",
+    "PacklistParser",
+    "SonglistDifficultiesParser",
+    "SonglistParser",
+    "St3ScoreParser",
+]

src/arcaea_offline/external/arcaea/common.py

@@ -1,17 +1,45 @@
+import contextlib
 import json
+import math
+import time
 from os import PathLike
 from typing import Any, List, Optional, Union
 
 from sqlalchemy.orm import DeclarativeBase, Session
 
 
+def fix_timestamp(timestamp: int) -> Union[int, None]:
+    """
+    Some of the `date` column in st3 are strangely truncated. For example,
+    a `1670283375` may be truncated to `167028`, even `1`. Yes, a single `1`.
+
+    To properly handle this situation, we check the timestamp's digits.
+    If `digits < 5`, we treat this timestamp as a `None`. Otherwise, we try to
+    fix the timestamp.
+
+    :param timestamp: a POSIX timestamp
+    :return: `None` if the timestamp's digits < 5, otherwise a fixed POSIX timestamp
+    """
+    # find digit length from https://stackoverflow.com/a/2189827/16484891
+    # CC BY-SA 2.5
+    # this might give incorrect result when timestamp > 999999999999997,
+    # see https://stackoverflow.com/a/28883802/16484891 (CC BY-SA 4.0).
+    # but that's way too later than 9999-12-31 23:59:59, 253402271999,
+    # I don't think Arcaea would still be an active updated game by then.
+    # so don't mind those small issues, just use this.
+    digits = int(math.log10(abs(timestamp))) + 1 if timestamp != 0 else 1
+    if digits < 5:
+        return None
+    timestamp_str = str(timestamp)
+    current_timestamp_digits = int(math.log10(int(time.time()))) + 1
+    timestamp_str = timestamp_str.ljust(current_timestamp_digits, "0")
+    return int(timestamp_str, 10)
+
+
 def to_db_value(val: Any) -> Any:
     if not val:
         return None
-    elif isinstance(val, list):
-        return json.dumps(val, ensure_ascii=False)
-    else:
-        return val
+    return json.dumps(val, ensure_ascii=False) if isinstance(val, list) else val
 
 
 def is_localized(item: dict, key: str, append_localized: bool = True):
@@ -43,8 +71,27 @@ class ArcaeaParser:
     def __init__(self, filepath: Union[str, bytes, PathLike]):
         self.filepath = filepath
 
+    def read_file_text(self):
+        file_handle = None
+
+        with contextlib.suppress(TypeError):
+            # original open
+            file_handle = open(self.filepath, "r", encoding="utf-8")
+
+        if file_handle is None:
+            try:
+                # or maybe a `pathlib.Path` subset
+                # or an `importlib.resources.abc.Traversable` like object
+                # e.g. `zipfile.Path`
+                file_handle = self.filepath.open(mode="r", encoding="utf-8")  # type: ignore
+            except Exception as e:
+                raise ValueError("Invalid `filepath`.") from e
+
+        with file_handle:
+            return file_handle.read()
+
     def parse(self) -> List[DeclarativeBase]:
-        ...
+        raise NotImplementedError()
 
     def write_database(self, session: Session):
         results = self.parse()

src/arcaea_offline/external/arcaea/online.py

@@ -0,0 +1,72 @@
+import json
+import logging
+from datetime import datetime
+from typing import Dict, List, Literal, Optional, TypedDict
+
+from ...models import Score
+from .common import ArcaeaParser, fix_timestamp
+
+logger = logging.getLogger(__name__)
+
+
+class TWebApiRatingMeScoreItem(TypedDict):
+    song_id: str
+    difficulty: int
+    modifier: int
+    rating: float
+    score: int
+    perfect_count: int
+    near_count: int
+    miss_count: int
+    clear_type: int
+    title: Dict[Literal["ja", "en"], str]
+    artist: str
+    time_played: int
+    bg: str
+
+
+class TWebApiRatingMeValue(TypedDict):
+    best_rated_scores: List[TWebApiRatingMeScoreItem]
+    recent_rated_scores: List[TWebApiRatingMeScoreItem]
+
+
+class TWebApiRatingMeResult(TypedDict):
+    success: bool
+    error_code: Optional[int]
+    value: Optional[TWebApiRatingMeValue]
+
+
+class ArcaeaOnlineParser(ArcaeaParser):
+    def parse(self) -> List[Score]:
+        api_result_root: TWebApiRatingMeResult = json.loads(self.read_file_text())
+
+        api_result_value = api_result_root.get("value")
+        if not api_result_value:
+            error_code = api_result_root.get("error_code")
+            raise ValueError(f"Cannot parse API result, error code {error_code}")
+
+        best30_score_items = api_result_value.get("best_rated_scores", [])
+        recent_score_items = api_result_value.get("recent_rated_scores", [])
+        score_items = best30_score_items + recent_score_items
+
+        date_text = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+        results: List[Score] = []
+        for score_item in score_items:
+            score = Score()
+            score.song_id = score_item["song_id"]
+            score.rating_class = score_item["difficulty"]
+            score.score = score_item["score"]
+            score.pure = score_item["perfect_count"]
+            score.far = score_item["near_count"]
+            score.lost = score_item["miss_count"]
+            score.date = fix_timestamp(int(score_item["time_played"] / 1000))
+            score.modifier = score_item["modifier"]
+            score.clear_type = score_item["clear_type"]
+
+            if score.lost == 0:
+                score.max_recall = score.pure + score.far
+
+            score.comment = f"Parsed from web API at {date_text}"
+            results.append(score)
+        return results

src/arcaea_offline/external/arcaea/packlist.py

@@ -6,15 +6,13 @@ from .common import ArcaeaParser, is_localized, set_model_localized_attrs
 
 
 class PacklistParser(ArcaeaParser):
-    def __init__(self, filepath):
-        super().__init__(filepath)
-
     def parse(self) -> List[Union[Pack, PackLocalized]]:
-        with open(self.filepath, "r", encoding="utf-8") as pl_f:
-            packlist_json_root = json.loads(pl_f.read())
+        packlist_json_root = json.loads(self.read_file_text())
 
         packlist_json = packlist_json_root["packs"]
-        results = []
+        results: List[Union[Pack, PackLocalized]] = [
+            Pack(id="single", name="Memory Archive")
+        ]
         for item in packlist_json:
             pack = Pack()
             pack.id = item["id"]

src/arcaea_offline/external/arcaea/songlist.py

@@ -1,17 +1,15 @@
 import json
 from typing import List, Union
 
-from ...models.songs import Chart, ChartLocalized, Song, SongLocalized
+from ...models.songs import Difficulty, DifficultyLocalized, Song, SongLocalized
 from .common import ArcaeaParser, is_localized, set_model_localized_attrs, to_db_value
 
 
 class SonglistParser(ArcaeaParser):
-    def __init__(self, filepath):
-        super().__init__(filepath)
-
-    def parse(self) -> List[Union[Song, SongLocalized, Chart, ChartLocalized]]:
-        with open(self.filepath, "r", encoding="utf-8") as sl_f:
-            songlist_json_root = json.loads(sl_f.read())
+    def parse(
+        self,
+    ) -> List[Union[Song, SongLocalized, Difficulty, DifficultyLocalized]]:
+        songlist_json_root = json.loads(self.read_file_text())
 
         songlist_json = songlist_json_root["songs"]
         results = []
@@ -60,12 +58,8 @@ class SonglistParser(ArcaeaParser):
 
 
 class SonglistDifficultiesParser(ArcaeaParser):
-    def __init__(self, filepath):
-        self.filepath = filepath
-
-    def parse(self) -> List[Union[Chart, ChartLocalized]]:
-        with open(self.filepath, "r", encoding="utf-8") as sl_f:
-            songlist_json_root = json.loads(sl_f.read())
+    def parse(self) -> List[Union[Difficulty, DifficultyLocalized]]:
+        songlist_json_root = json.loads(self.read_file_text())
 
         songlist_json = songlist_json_root["songs"]
         results = []
@@ -74,7 +68,10 @@ class SonglistDifficultiesParser(ArcaeaParser):
                 continue
 
             for item in song_item["difficulties"]:
-                chart = Chart(song_id=song_item["id"])
+                if item["rating"] == 0:
+                    continue
+
+                chart = Difficulty(song_id=song_item["id"])
                 chart.rating_class = item["ratingClass"]
                 chart.rating = item["rating"]
                 chart.rating_plus = item.get("ratingPlus") or False
@@ -94,7 +91,7 @@ class SonglistDifficultiesParser(ArcaeaParser):
                 results.append(chart)
 
                 if is_localized(item, "title") or is_localized(item, "artist"):
-                    chart_localized = ChartLocalized(
+                    chart_localized = DifficultyLocalized(
                         song_id=chart.song_id, rating_class=chart.rating_class
                     )
                     set_model_localized_attrs(chart_localized, item, "title")

src/arcaea_offline/external/arcaea/st3.py

@@ -6,33 +6,34 @@ from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from ...models.scores import Score
-from .common import ArcaeaParser
+from .common import ArcaeaParser, fix_timestamp
 
 logger = logging.getLogger(__name__)
 
 
 class St3ScoreParser(ArcaeaParser):
-    CLEAR_TYPES_MAP = {0: -1, 1: 1, 2: 1, 3: 1, 4: 1, 5: 1}
-
-    def __init__(self, filepath):
-        super().__init__(filepath)
-
     def parse(self) -> List[Score]:
         items = []
         with sqlite3.connect(self.filepath) as st3_conn:
             cursor = st3_conn.cursor()
             db_scores = cursor.execute(
-                "SELECT songId, songDifficulty, score, perfectCount, nearCount, missCount, date FROM scores"
+                "SELECT songId, songDifficulty, score, perfectCount, nearCount, missCount, "
+                "date, modifier FROM scores"
             ).fetchall()
-            for song_id, rating_class, score, pure, far, lost, date in db_scores:
-                db_clear_type = cursor.execute(
+            for (
+                song_id,
+                rating_class,
+                score,
+                pure,
+                far,
+                lost,
+                date,
+                modifier,
+            ) in db_scores:
+                clear_type = cursor.execute(
                     "SELECT clearType FROM cleartypes WHERE songId = ? AND songDifficulty = ?",
                     (song_id, rating_class),
                 ).fetchone()[0]
-                r10_clear_type = self.CLEAR_TYPES_MAP[db_clear_type]
-
-                date_str = str(date)
-                date = None if len(date_str) < 7 else int(date_str.ljust(10, "0"))
 
                 items.append(
                     Score(
@@ -42,8 +43,10 @@ class St3ScoreParser(ArcaeaParser):
                         pure=pure,
                         far=far,
                         lost=lost,
-                        date=date,
-                        r10_clear_type=r10_clear_type,
+                        date=fix_timestamp(date),
+                        modifier=modifier,
+                        clear_type=clear_type,
+                        comment="Parsed from st3",
                     )
                 )
 
@@ -62,8 +65,9 @@ class St3ScoreParser(ArcaeaParser):
 
             if query_score and skip_duplicate:
                 logger.info(
-                    f"{repr(parsed_score)} skipped because "
-                    f"potential duplicate item {repr(query_score)} found."
+                    "%r skipped because potential duplicate item %r found.",
+                    parsed_score,
+                    query_score,
                 )
                 continue
             session.add(parsed_score)

src/arcaea_offline/external/arcsong/__init__.py

@@ -1 +1,3 @@
 from .arcsong_db import ArcsongDbParser
+
+__all__ = ["ArcsongDbParser"]

src/arcaea_offline/external/arcsong/arcsong_db.py

@@ -3,7 +3,7 @@ from typing import List
 
 from sqlalchemy.orm import Session
 
-from ...models.songs import ChartInfo
+from arcaea_offline.database.models.v4 import ChartInfo
 
 
 class ArcsongDbParser:
@@ -22,7 +22,7 @@ class ArcsongDbParser:
                     song_id=result[0],
                     rating_class=result[1],
                     constant=result[2],
-                    note=result[3] or None,
+                    notes=result[3] or None,
                 )
                 results.append(chart)
 

src/arcaea_offline/external/arcsong/arcsong_json.py

@@ -0,0 +1,157 @@
+import logging
+import re
+from typing import List, Optional, TypedDict
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from arcaea_offline.database.models.v4 import (
+    ChartInfo,
+    Difficulty,
+    DifficultyLocalized,
+    Pack,
+    Song,
+    SongLocalized,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TArcSongJsonDifficultyItem(TypedDict):
+    name_en: str
+    name_jp: str
+    artist: str
+    bpm: str
+    bpm_base: float
+    set: str
+    set_friendly: str
+    time: int
+    side: int
+    world_unlock: bool
+    remote_download: bool
+    bg: str
+    date: int
+    version: str
+    difficulty: int
+    rating: int
+    note: int
+    chart_designer: str
+    jacket_designer: str
+    jacket_override: bool
+    audio_override: bool
+
+
+class TArcSongJsonSongItem(TypedDict):
+    song_id: str
+    difficulties: List[TArcSongJsonDifficultyItem]
+    alias: List[str]
+
+
+class TArcSongJson(TypedDict):
+    songs: List[TArcSongJsonSongItem]
+
+
+class ArcSongJsonBuilder:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def get_difficulty_item(
+        self,
+        difficulty: Difficulty,
+        song: Song,
+        pack: Pack,
+        song_localized: Optional[SongLocalized],
+    ) -> TArcSongJsonDifficultyItem:
+        if "_append_" in pack.id:
+            base_pack = self.session.scalar(
+                select(Pack).where(Pack.id == re.sub(r"_append_.*$", "", pack.id))
+            )
+        else:
+            base_pack = None
+
+        difficulty_localized = self.session.scalar(
+            select(DifficultyLocalized).where(
+                (DifficultyLocalized.song_id == difficulty.song_id)
+                & (DifficultyLocalized.rating_class == difficulty.rating_class)
+            )
+        )
+        chart_info = self.session.scalar(
+            select(ChartInfo).where(
+                (ChartInfo.song_id == difficulty.song_id)
+                & (ChartInfo.rating_class == difficulty.rating_class)
+            )
+        )
+
+        if difficulty_localized:
+            name_jp = difficulty_localized.title_ja or ""
+        elif song_localized:
+            name_jp = song_localized.title_ja or ""
+        else:
+            name_jp = ""
+
+        return {
+            "name_en": difficulty.title or song.title,
+            "name_jp": name_jp,
+            "artist": difficulty.artist or song.artist,
+            "bpm": difficulty.bpm or song.bpm or "",
+            "bpm_base": difficulty.bpm_base or song.bpm_base or 0.0,
+            "set": song.set,
+            "set_friendly": f"{base_pack.name} - {pack.name}"
+            if base_pack
+            else pack.name,
+            "time": 0,
+            "side": song.side or 0,
+            "world_unlock": False,
+            "remote_download": False,
+            "bg": difficulty.bg or song.bg or "",
+            "date": difficulty.date or song.date or 0,
+            "version": difficulty.version or song.version or "",
+            "difficulty": difficulty.rating * 2 + int(difficulty.rating_plus),
+            "rating": chart_info.constant or 0 if chart_info else 0,
+            "note": chart_info.notes or 0 if chart_info else 0,
+            "chart_designer": difficulty.chart_designer or "",
+            "jacket_designer": difficulty.jacket_desginer or "",
+            "jacket_override": difficulty.jacket_override,
+            "audio_override": difficulty.audio_override,
+        }
+
+    def get_song_item(self, song: Song) -> TArcSongJsonSongItem:
+        difficulties = self.session.scalars(
+            select(Difficulty).where(Difficulty.song_id == song.id)
+        )
+
+        pack = self.session.scalar(select(Pack).where(Pack.id == song.set))
+        if not pack:
+            logger.warning(
+                'Cannot find pack "%s", using placeholder instead.', song.set
+            )
+            pack = Pack(id="unknown", name="Unknown", description="__PLACEHOLDER__")
+        song_localized = self.session.scalar(
+            select(SongLocalized).where(SongLocalized.id == song.id)
+        )
+
+        return {
+            "song_id": song.id,
+            "difficulties": [
+                self.get_difficulty_item(difficulty, song, pack, song_localized)
+                for difficulty in difficulties
+            ],
+            "alias": [],
+        }
+
+    def generate_arcsong_json(self) -> TArcSongJson:
+        songs = self.session.scalars(select(Song))
+        arcsong_songs = []
+        for song in songs:
+            proceed = self.session.scalar(
+                select(func.count(Difficulty.rating_class)).where(
+                    Difficulty.song_id == song.id
+                )
+            )
+
+            if not proceed:
+                continue
+
+            arcsong_songs.append(self.get_song_item(song))
+
+        return {"songs": arcsong_songs}

src/arcaea_offline/external/chart_info_db/__init__.py

@@ -0,0 +1,3 @@
+from .parser import ChartInfoDbParser
+
+__all__ = ["ChartInfoDbParser"]

src/arcaea_offline/external/chart_info_db/parser.py

@@ -0,0 +1,35 @@
+import contextlib
+import sqlite3
+from typing import List
+
+from sqlalchemy.orm import Session
+
+from ...models.songs import ChartInfo
+
+
+class ChartInfoDbParser:
+    def __init__(self, filepath):
+        self.filepath = filepath
+
+    def parse(self) -> List[ChartInfo]:
+        results = []
+        with sqlite3.connect(self.filepath) as conn:
+            with contextlib.closing(conn.cursor()) as cursor:
+                db_results = cursor.execute(
+                    "SELECT song_id, rating_class, constant, notes FROM charts_info"
+                ).fetchall()
+                for result in db_results:
+                    chart = ChartInfo(
+                        song_id=result[0],
+                        rating_class=result[1],
+                        constant=result[2],
+                        notes=result[3] or None,
+                    )
+                    results.append(chart)
+
+        return results
+
+    def write_database(self, session: Session):
+        results = self.parse()
+        for result in results:
+            session.merge(result)

src/arcaea_offline/external/exports/exporters.py

@@ -0,0 +1,38 @@
+from arcaea_offline.database.models.v4 import Score
+
+from .types import ArcaeaOfflineDEFV2_ScoreItem, ScoreExport
+
+
+def score(score: Score) -> ScoreExport:
+    return {
+        "id": score.id,
+        "song_id": score.song_id,
+        "rating_class": score.rating_class,
+        "score": score.score,
+        "pure": score.pure,
+        "far": score.far,
+        "lost": score.lost,
+        "date": score.date,
+        "max_recall": score.max_recall,
+        "modifier": score.modifier,
+        "clear_type": score.clear_type,
+        "comment": score.comment,
+    }
+
+
+def score_def_v2(score: Score) -> ArcaeaOfflineDEFV2_ScoreItem:
+    return {
+        "id": score.id,
+        "songId": score.song_id,
+        "ratingClass": score.rating_class,
+        "score": score.score,
+        "pure": score.pure,
+        "far": score.far,
+        "lost": score.lost,
+        "date": score.date,
+        "maxRecall": score.max_recall,
+        "modifier": score.modifier,
+        "clearType": score.clear_type,
+        "source": None,
+        "comment": score.comment,
+    }

src/arcaea_offline/external/exports/types.py

@@ -0,0 +1,45 @@
+from typing import List, Literal, Optional, TypedDict
+
+
+class ScoreExport(TypedDict):
+    id: int
+    song_id: str
+    rating_class: int
+    score: int
+    pure: Optional[int]
+    far: Optional[int]
+    lost: Optional[int]
+    date: Optional[int]
+    max_recall: Optional[int]
+    modifier: Optional[int]
+    clear_type: Optional[int]
+    comment: Optional[str]
+
+
+class ArcaeaOfflineDEFV2_ScoreItem(TypedDict, total=False):
+    id: Optional[int]
+    songId: str
+    ratingClass: int
+    score: int
+    pure: Optional[int]
+    far: Optional[int]
+    lost: Optional[int]
+    date: Optional[int]
+    maxRecall: Optional[int]
+    modifier: Optional[int]
+    clearType: Optional[int]
+    source: Optional[str]
+    comment: Optional[str]
+
+
+ArcaeaOfflineDEFV2_Score = TypedDict(
+    "ArcaeaOfflineDEFV2_Score",
+    {
+        "$schema": Literal[
+            "https://arcaeaoffline.sevive.xyz/schemas/def/v2/score.schema.json"
+        ],
+        "type": Literal["score"],
+        "version": Literal[2],
+        "scores": List[ArcaeaOfflineDEFV2_ScoreItem],
+    },
+)

src/arcaea_offline/external/importers/arcaea/common.py

@@ -0,0 +1,31 @@
+from typing import Union
+
+
+def fix_timestamp(timestamp: int) -> Union[int, None]:
+    """
+    Some of the `date` column in st3 are unexpectedly truncated. For example,
+    a `1670283375` may be truncated to `167028`, even a single `1`.
+
+    To properly handle this:
+
+    If `timestamp > 1489017600` (the release date of Arcaea), consider it's ok.
+
+    Otherwise, if the timestamp is 'fixable'
+    (`1489 <= timestamp <= 9999` or `timestamp > 14889`),
+    pad zeros to the end of timestamp.
+    For example, a `1566` will be padded to `1566000000`.
+
+    Otherwise, treat the timestamp as `None`.
+
+    :param timestamp: `date` value
+    """
+    if timestamp > 1489017600:  # noqa: PLR2004
+        return timestamp
+
+    timestamp_fixable = 1489 <= timestamp <= 9999 or timestamp > 14889  # noqa: PLR2004
+    if not timestamp_fixable:
+        return None
+
+    timestamp_str = str(timestamp)
+    timestamp_str = timestamp_str.ljust(10, "0")
+    return int(timestamp_str, 10)

src/arcaea_offline/external/importers/arcaea/lists.py

@@ -0,0 +1,178 @@
+"""
+packlist and songlist parsers
+"""
+
+import json
+from typing import List, Union
+
+from arcaea_offline.constants.enums import (
+    ArcaeaLanguage,
+    ArcaeaRatingClass,
+    ArcaeaSongSide,
+)
+from arcaea_offline.database.models.v5 import (
+    Difficulty,
+    DifficultyLocalized,
+    Pack,
+    PackLocalized,
+    Song,
+    SongLocalized,
+    SongSearchWord,
+)
+
+
+class ArcaeaListParser:
+    def __init__(self, list_text: str):
+        self.list_text = list_text
+
+
+class PacklistParser(ArcaeaListParser):
+    def parse(self) -> List[Union[Pack, PackLocalized]]:
+        root = json.loads(self.list_text)
+
+        packs = root["packs"]
+        results: List[Union[Pack, PackLocalized]] = [
+            Pack(id="single", name="Memory Archive")
+        ]
+        for item in packs:
+            pack = Pack()
+            pack.id = item["id"]
+            pack.name = item["name_localized"]["en"]
+            pack.description = item["description_localized"]["en"] or None
+            results.append(pack)
+
+            for key in ArcaeaLanguage:
+                name_localized = item["name_localized"].get(key.value, None)
+                description_localized = item["description_localized"].get(
+                    key.value, None
+                )
+
+                if name_localized or description_localized:
+                    pack_localized = PackLocalized(id=pack.id)
+                    pack_localized.lang = key.value
+                    pack_localized.name = name_localized
+                    pack_localized.description = description_localized
+                    results.append(pack_localized)
+
+        return results
+
+
+class SonglistParser(ArcaeaListParser):
+    def parse_songs(self) -> List[Union[Song, SongLocalized, SongSearchWord]]:
+        root = json.loads(self.list_text)
+
+        songs = root["songs"]
+        results = []
+        for item in songs:
+            song = Song()
+            song.idx = item["idx"]
+            song.id = item["id"]
+            song.title = item["title_localized"]["en"]
+            song.artist = item["artist"]
+            song.bpm = item["bpm"]
+            song.bpm_base = item["bpm_base"]
+            song.pack_id = item["set"]
+            song.audio_preview = item["audioPreview"]
+            song.audio_preview_end = item["audioPreviewEnd"]
+            song.side = ArcaeaSongSide(item["side"])
+            song.version = item["version"]
+            song.date = item["date"]
+            song.bg = item.get("bg")
+            song.bg_inverse = item.get("bg_inverse")
+            if item.get("bg_daynight"):
+                song.bg_day = item["bg_daynight"].get("day")
+                song.bg_night = item["bg_daynight"].get("night")
+            if item.get("source_localized"):
+                song.source = item["source_localized"]["en"]
+            song.source_copyright = item.get("source_copyright")
+            results.append(song)
+
+            for lang in ArcaeaLanguage:
+                # SongLocalized objects
+                title_localized = item["title_localized"].get(lang.value, None)
+                source_localized = item.get("source_localized", {}).get(
+                    lang.value, None
+                )
+
+                if title_localized or source_localized:
+                    song_localized = SongLocalized(id=song.id)
+                    song_localized.lang = lang.value
+                    song_localized.title = title_localized
+                    song_localized.source = source_localized
+                    results.append(song_localized)
+
+                # SongSearchTitle
+                search_titles = item.get("search_title", {}).get(lang.value, None)
+                if search_titles:
+                    for search_title in search_titles:
+                        song_search_word = SongSearchWord(
+                            id=song.id, lang=lang.value, type=1, value=search_title
+                        )
+                        results.append(song_search_word)
+
+                search_artists = item.get("search_artist", {}).get(lang.value, None)
+                if search_artists:
+                    for search_artist in search_artists:
+                        song_search_word = SongSearchWord(
+                            id=song.id, lang=lang.value, type=2, value=search_artist
+                        )
+                        results.append(song_search_word)
+
+        return results
+
+    def parse_difficulties(self) -> List[Union[Difficulty, DifficultyLocalized]]:
+        root = json.loads(self.list_text)
+
+        songs = root["songs"]
+        results = []
+        for song in songs:
+            difficulties = song.get("difficulties")
+            if not difficulties:
+                continue
+
+            for item in difficulties:
+                if item["rating"] == 0:
+                    continue
+
+                difficulty = Difficulty()
+                difficulty.song_id = song["id"]
+                difficulty.rating_class = ArcaeaRatingClass(item["ratingClass"])
+                difficulty.rating = item["rating"]
+                difficulty.rating_plus = item.get("ratingPlus") or False
+                difficulty.chart_designer = item["chartDesigner"]
+                difficulty.jacket_desginer = item.get("jacketDesigner") or None
+                difficulty.audio_override = item.get("audioOverride") or False
+                difficulty.jacket_override = item.get("jacketOverride") or False
+                difficulty.jacket_night = item.get("jacketNight") or None
+                difficulty.title = item.get("title_localized", {}).get("en") or None
+                difficulty.artist = item.get("artist") or None
+                difficulty.bg = item.get("bg") or None
+                difficulty.bg_inverse = item.get("bg_inverse")
+                difficulty.bpm = item.get("bpm") or None
+                difficulty.bpm_base = item.get("bpm_base") or None
+                difficulty.version = item.get("version") or None
+                difficulty.date = item.get("date") or None
+                results.append(difficulty)
+
+                for lang in ArcaeaLanguage:
+                    title_localized = item.get("title_localized", {}).get(
+                        lang.value, None
+                    )
+                    artist_localized = item.get("artist_localized", {}).get(
+                        lang.value, None
+                    )
+
+                    if title_localized or artist_localized:
+                        difficulty_localized = DifficultyLocalized(
+                            song_id=difficulty.song_id,
+                            rating_class=difficulty.rating_class,
+                        )
+                        difficulty_localized.lang = lang.value
+                        difficulty_localized.title = title_localized
+                        difficulty_localized.artist = artist_localized
+                        results.append(difficulty_localized)
+
+        return results
+
+    def parse_all(self):
+        return self.parse_songs() + self.parse_difficulties()

src/arcaea_offline/external/importers/arcaea/st3.py

@@ -0,0 +1,118 @@
+"""
+Game database play results importer
+"""
+
+import logging
+import sqlite3
+from datetime import datetime, timezone
+from typing import List, overload
+
+from arcaea_offline.constants.enums import (
+    ArcaeaPlayResultClearType,
+    ArcaeaPlayResultModifier,
+    ArcaeaRatingClass,
+)
+from arcaea_offline.database.models.v5 import PlayResult
+
+from .common import fix_timestamp
+
+logger = logging.getLogger(__name__)
+
+
+class St3Parser:
+    @classmethod
+    @overload
+    def parse(cls, db: sqlite3.Connection) -> List[PlayResult]: ...
+
+    @classmethod
+    @overload
+    def parse(cls, db: sqlite3.Cursor) -> List[PlayResult]: ...
+
+    @classmethod
+    def parse(cls, db) -> List[PlayResult]:
+        if isinstance(db, sqlite3.Connection):
+            return cls.parse(db.cursor())
+
+        if not isinstance(db, sqlite3.Cursor):
+            raise TypeError(
+                "Unknown overload of `db`. Expected `sqlite3.Connection` or `sqlite3.Cursor`."
+            )
+
+        entities = []
+        query_results = db.execute("""
+            SELECT s.id AS _id, s.songId, s.songDifficulty AS ratingClass, s.score,
+                s.perfectCount AS pure, s.nearCount AS far, s.missCount AS lost,
+                s.`date`, s.modifier, ct.clearType
+            FROM scores s JOIN cleartypes ct
+            ON s.songId = ct.songId AND s.songDifficulty = ct.songDifficulty""")
+        # maybe `s.id = ct.id`?
+
+        now = datetime.now(tz=timezone.utc)
+        import_comment = (
+            f"Imported from st3 at {now.astimezone().isoformat(timespec='seconds')}"
+        )
+        for result in query_results:
+            (
+                _id,
+                song_id,
+                rating_class,
+                score,
+                pure,
+                far,
+                lost,
+                date,
+                modifier,
+                clear_type,
+            ) = result
+
+            try:
+                rating_class_enum = ArcaeaRatingClass(rating_class)
+            except ValueError:
+                logger.warning(
+                    "Unknown rating class [%r] at entry id %d, skipping!",
+                    rating_class,
+                    _id,
+                )
+                continue
+
+            try:
+                clear_type_enum = ArcaeaPlayResultClearType(clear_type)
+            except ValueError:
+                logger.warning(
+                    "Unknown clear type [%r] at entry id %d, falling back to `None`!",
+                    clear_type,
+                    _id,
+                )
+                clear_type_enum = None
+
+            try:
+                modifier_enum = ArcaeaPlayResultModifier(modifier)
+            except ValueError:
+                logger.warning(
+                    "Unknown modifier [%r] at entry id %d, falling back to `None`!",
+                    modifier,
+                    _id,
+                )
+                modifier_enum = None
+
+            if date := fix_timestamp(date):
+                date = datetime.fromtimestamp(date).astimezone()
+            else:
+                date = None
+
+            entities.append(
+                PlayResult(
+                    song_id=song_id,
+                    rating_class=rating_class_enum,
+                    score=score,
+                    pure=pure,
+                    far=far,
+                    lost=lost,
+                    date=date,
+                    modifier=modifier_enum,
+                    clear_type=clear_type_enum,
+                    comment=import_comment,
+                )
+            )
+
+        return entities

src/arcaea_offline/external/smartrte/__init__.py

@@ -0,0 +1,3 @@
+from .b30_csv import SmartRteB30CsvConverter
+
+__all__ = ["SmartRteB30CsvConverter"]

src/arcaea_offline/external/smartrte/b30_csv.py

@@ -0,0 +1,64 @@
+from sqlalchemy.orm import Session
+
+from ...models import Chart, ScoreBest
+from ...utils.rating import rating_class_to_text
+
+
+class SmartRteB30CsvConverter:
+    CSV_ROWS = [
+        "songname",
+        "songId",
+        "Difficulty",
+        "score",
+        "Perfect",
+        "criticalPerfect",
+        "Far",
+        "Lost",
+        "Constant",
+        "singlePTT",
+    ]
+
+    def __init__(
+        self,
+        session: Session,
+    ):
+        self.session = session
+
+    def rows(self) -> list:
+        csv_rows = [self.CSV_ROWS.copy()]
+
+        with self.session as session:
+            results = (
+                session.query(
+                    Chart.title,
+                    ScoreBest.song_id,
+                    ScoreBest.rating_class,
+                    ScoreBest.score,
+                    ScoreBest.pure,
+                    ScoreBest.shiny_pure,
+                    ScoreBest.far,
+                    ScoreBest.lost,
+                    Chart.constant,
+                    ScoreBest.potential,
+                )
+                .join(
+                    Chart,
+                    (Chart.song_id == ScoreBest.song_id)
+                    & (Chart.rating_class == ScoreBest.rating_class),
+                )
+                .all()
+            )
+
+            for result in results:
+                # replace the comma in song title because the target project
+                # cannot handle quoted string
+                result = list(result)
+                result[0] = result[0].replace(",", "")
+                result[2] = rating_class_to_text(result[2])
+                # divide constant to float
+                result[-2] = result[-2] / 10
+                # round potential
+                result[-1] = round(result[-1], 5)
+                csv_rows.append(result)
+
+        return csv_rows

src/arcaea_offline/utils/formatters/__init__.py

@@ -0,0 +1,7 @@
+from .play_result import PlayResultFormatter
+from .rating_class import RatingClassFormatter
+
+__all__ = [
+    "PlayResultFormatter",
+    "RatingClassFormatter",
+]

src/arcaea_offline/utils/formatters/play_result.py

@@ -0,0 +1,143 @@
+from typing import Any, Literal, overload
+
+from arcaea_offline.constants.enums import (
+    ArcaeaPlayResultClearType,
+    ArcaeaPlayResultModifier,
+)
+from arcaea_offline.constants.play_result import ScoreLowerLimits
+
+
+class PlayResultFormatter:
+    SCORE_GRADE_FORMAT_RESULTS = Literal["EX+", "EX", "AA", "A", "B", "C", "D"]
+
+    @staticmethod
+    def score_grade(score: int) -> SCORE_GRADE_FORMAT_RESULTS:
+        """
+        Returns the score grade, e.g. EX+.
+
+        Raises `ValueError` if the score is negative.
+        """
+        if not isinstance(score, int):
+            raise TypeError(f"Unsupported type {type(score)}, cannot format")
+
+        if score >= ScoreLowerLimits.EX_PLUS:
+            return "EX+"
+        elif score >= ScoreLowerLimits.EX:
+            return "EX"
+        elif score >= ScoreLowerLimits.AA:
+            return "AA"
+        elif score >= ScoreLowerLimits.A:
+            return "A"
+        elif score >= ScoreLowerLimits.B:
+            return "B"
+        elif score >= ScoreLowerLimits.C:
+            return "C"
+        elif score >= ScoreLowerLimits.D:
+            return "D"
+        else:
+            raise ValueError("score cannot be negative")
+
+    CLEAR_TYPE_FORMAT_RESULTS = Literal[
+        "TRACK LOST",
+        "NORMAL CLEAR",
+        "FULL RECALL",
+        "PURE MEMORY",
+        "EASY CLEAR",
+        "HARD CLEAR",
+        "UNKNOWN",
+        "None",
+    ]
+
+    @overload
+    @classmethod
+    def clear_type(
+        cls, clear_type: ArcaeaPlayResultClearType
+    ) -> CLEAR_TYPE_FORMAT_RESULTS:
+        """
+        Returns the uppercased clear type name, e.g. NORMAL CLEAR.
+        """
+        ...
+
+    @overload
+    @classmethod
+    def clear_type(cls, clear_type: int) -> CLEAR_TYPE_FORMAT_RESULTS:
+        """
+        Returns the uppercased clear type name, e.g. NORMAL CLEAR.
+
+        The integer will be converted to `ArcaeaPlayResultClearType` enum,
+        and will return "UNKNOWN" if the convertion fails.
+
+        Raises `ValueError` if the integer is negative.
+        """
+        ...
+
+    @overload
+    @classmethod
+    def clear_type(cls, clear_type: None) -> CLEAR_TYPE_FORMAT_RESULTS:
+        """
+        Returns "None"
+        """
+        ...
+
+    @classmethod
+    def clear_type(cls, clear_type: Any) -> CLEAR_TYPE_FORMAT_RESULTS:
+        if clear_type is None:
+            return "None"
+        elif isinstance(clear_type, ArcaeaPlayResultClearType):
+            return clear_type.name.replace("_", " ").upper()  # type: ignore
+        elif isinstance(clear_type, int):
+            if clear_type < 0:
+                raise ValueError("clear_type cannot be negative")
+            try:
+                return cls.clear_type(ArcaeaPlayResultClearType(clear_type))
+            except ValueError:
+                return "UNKNOWN"
+        else:
+            raise TypeError(f"Unsupported type {type(clear_type)}, cannot format")
+
+    MODIFIER_FORMAT_RESULTS = Literal["NORMAL", "EASY", "HARD", "UNKNOWN", "None"]
+
+    @overload
+    @classmethod
+    def modifier(cls, modifier: ArcaeaPlayResultModifier) -> MODIFIER_FORMAT_RESULTS:
+        """
+        Returns the uppercased clear type name, e.g. NORMAL CLEAR.
+        """
+        ...
+
+    @overload
+    @classmethod
+    def modifier(cls, modifier: int) -> MODIFIER_FORMAT_RESULTS:
+        """
+        Returns the uppercased clear type name, e.g. NORMAL CLEAR.
+
+        The integer will be converted to `ArcaeaPlayResultModifier` enum,
+        and will return "UNKNOWN" if the convertion fails.
+
+        Raises `ValueError` if the integer is negative.
+        """
+        ...
+
+    @overload
+    @classmethod
+    def modifier(cls, modifier: None) -> MODIFIER_FORMAT_RESULTS:
+        """
+        Returns "None"
+        """
+        ...
+
+    @classmethod
+    def modifier(cls, modifier: Any) -> MODIFIER_FORMAT_RESULTS:
+        if modifier is None:
+            return "None"
+        elif isinstance(modifier, ArcaeaPlayResultModifier):
+            return modifier.name
+        elif isinstance(modifier, int):
+            if modifier < 0:
+                raise ValueError("modifier cannot be negative")
+            try:
+                return cls.modifier(ArcaeaPlayResultModifier(modifier))
+            except ValueError:
+                return "UNKNOWN"
+        else:
+            raise TypeError(f"Unsupported type {type(modifier)}, cannot format")

src/arcaea_offline/utils/formatters/rating_class.py

@@ -0,0 +1,83 @@
+from typing import Any, Literal, overload
+
+from arcaea_offline.constants.enums import ArcaeaRatingClass
+
+
+class RatingClassFormatter:
+    abbreviations = {
+        ArcaeaRatingClass.PAST: "PST",
+        ArcaeaRatingClass.PRESENT: "PRS",
+        ArcaeaRatingClass.FUTURE: "FTR",
+        ArcaeaRatingClass.BEYOND: "BYD",
+        ArcaeaRatingClass.ETERNAL: "ETR",
+    }
+
+    NAME_FORMAT_RESULTS = Literal[
+        "Past", "Present", "Future", "Beyond", "Eternal", "Unknown"
+    ]
+
+    @overload
+    @classmethod
+    def name(cls, rating_class: ArcaeaRatingClass) -> NAME_FORMAT_RESULTS:
+        """
+        Returns the capitalized rating class name, e.g. Future.
+        """
+        ...
+
+    @overload
+    @classmethod
+    def name(cls, rating_class: int) -> NAME_FORMAT_RESULTS:
+        """
+        Returns the capitalized rating class name, e.g. Future.
+
+        The integer will be converted to `ArcaeaRatingClass` enum,
+        and will return "Unknown" if the convertion fails.
+        """
+        ...
+
+    @classmethod
+    def name(cls, rating_class: Any) -> NAME_FORMAT_RESULTS:
+        if isinstance(rating_class, ArcaeaRatingClass):
+            return rating_class.name.lower().capitalize()  # type: ignore
+        elif isinstance(rating_class, int):
+            try:
+                return cls.name(ArcaeaRatingClass(rating_class))
+            except ValueError:
+                return "Unknown"
+        else:
+            raise TypeError(f"Unsupported type: {type(rating_class)}, cannot format")
+
+    ABBREVIATION_FORMAT_RESULTS = Literal["PST", "PRS", "FTR", "BYD", "ETR", "UNK"]
+
+    @overload
+    @classmethod
+    def abbreviation(
+        cls, rating_class: ArcaeaRatingClass
+    ) -> ABBREVIATION_FORMAT_RESULTS:
+        """
+        Returns the uppercased rating class name, e.g. FTR.
+        """
+        ...
+
+    @overload
+    @classmethod
+    def abbreviation(cls, rating_class: int) -> ABBREVIATION_FORMAT_RESULTS:
+        """
+        Returns the uppercased rating class name, e.g. FTR.
+
+        The integer will be converted to `ArcaeaRatingClass` enum,
+        and will return "UNK" if the convertion fails.
+        """
+        ...
+
+    @classmethod
+    def abbreviation(cls, rating_class: Any) -> ABBREVIATION_FORMAT_RESULTS:
+        if isinstance(rating_class, ArcaeaRatingClass):
+            return cls.abbreviations[rating_class]  # type: ignore
+        elif isinstance(rating_class, int):
+            try:
+                return cls.abbreviation(ArcaeaRatingClass(rating_class))
+            except ValueError:
+                return "UNK"
+        else:
+            raise TypeError(f"Unsupported type: {type(rating_class)}, cannot format")

src/arcaea_offline/utils/partner.py

@@ -0,0 +1,15 @@
+from datetime import datetime
+from enum import IntEnum
+
+
+class KanaeDayNight(IntEnum):
+    Day = 0
+    Night = 1
+
+
+def kanae_day_night(timestamp: int) -> KanaeDayNight:
+    """
+    :param timestamp: POSIX timestamp, which is passed to `datetime.fromtimestamp(timestamp)`.
+    """
+    dt = datetime.fromtimestamp(timestamp)
+    return KanaeDayNight.Day if 6 <= dt.hour <= 19 else KanaeDayNight.Night

tests/calculators/test_play_result.py

@@ -0,0 +1,42 @@
+from decimal import Decimal
+
+import pytest
+
+from arcaea_offline.calculators.play_result import PlayResultCalculators
+
+
+class TestPlayResultCalculators:
+    def test_score_modifier(self):
+        # Results from https://arcaea.fandom.com/wiki/Potential#Score_Modifier
+
+        assert PlayResultCalculators.score_modifier(10000000) == Decimal("2.0")
+        assert PlayResultCalculators.score_modifier(9900000) == Decimal("1.5")
+        assert PlayResultCalculators.score_modifier(9800000) == Decimal("1.0")
+        assert PlayResultCalculators.score_modifier(9500000) == Decimal("0.0")
+        assert PlayResultCalculators.score_modifier(9200000) == Decimal("-1.0")
+        assert PlayResultCalculators.score_modifier(8900000) == Decimal("-2.0")
+        assert PlayResultCalculators.score_modifier(8600000) == Decimal("-3.0")
+
+        assert PlayResultCalculators.score_modifier(0).quantize(
+            Decimal("-0.00")
+        ) == Decimal("-31.67")
+
+        pytest.raises(ValueError, PlayResultCalculators.score_modifier, -1)
+
+        pytest.raises(TypeError, PlayResultCalculators.score_modifier, "9800000")
+        pytest.raises(TypeError, PlayResultCalculators.score_modifier, None)
+        pytest.raises(TypeError, PlayResultCalculators.score_modifier, [])
+
+    def test_play_rating(self):
+        assert PlayResultCalculators.play_rating(10002221, 120) == Decimal("14.0")
+
+        assert PlayResultCalculators.play_rating(5500000, 120) == Decimal("0.0")
+
+        pytest.raises(TypeError, PlayResultCalculators.play_rating, "10002221", 120)
+        pytest.raises(TypeError, PlayResultCalculators.play_rating, 10002221, "120")
+        pytest.raises(TypeError, PlayResultCalculators.play_rating, "10002221", "120")
+
+        pytest.raises(TypeError, PlayResultCalculators.play_rating, 10002221, None)
+
+        pytest.raises(ValueError, PlayResultCalculators.play_rating, -1, 120)
+        pytest.raises(ValueError, PlayResultCalculators.play_rating, 10002221, -1)

tests/calculators/test_world.py

@@ -0,0 +1,74 @@
+from decimal import ROUND_FLOOR, Decimal
+
+from arcaea_offline.calculators.play_result import PlayResultCalculators
+from arcaea_offline.calculators.world import (
+    LegacyMapStepBooster,
+    PartnerBonus,
+    WorldMainMapCalculators,
+    WorldPlayResult,
+)
+
+
+class TestWorldMainMapCalculators:
+    def test_step_fandom(self):
+        # Final result from https://arcaea.fandom.com/wiki/World_Mode_Mechanics#Calculation
+        # CC BY-SA 3.0
+
+        booster = LegacyMapStepBooster(6, 250)
+        partner_bonus = PartnerBonus(step_bonus="+3.6")
+        play_result = WorldPlayResult(play_rating=Decimal("11.299"), partner_step=92)
+        result = WorldMainMapCalculators.step(
+            play_result, partner_bonus=partner_bonus, step_booster=booster
+        )
+
+        assert result.quantize(Decimal("0.000")) == Decimal("175.149")
+
+    def test_step(self):
+        # Results from actual play results, Arcaea v5.5.8c
+
+        def _quantize(decimal: Decimal) -> Decimal:
+            return decimal.quantize(Decimal("0.0"), rounding=ROUND_FLOOR)
+
+        # goldenslaughter FTR [9.7], 9906968
+        # 10.7 > 34.2 < 160
+        assert _quantize(
+            WorldMainMapCalculators.step(
+                WorldPlayResult(
+                    play_rating=PlayResultCalculators.play_rating(9906968, 97),
+                    partner_step=160,
+                )
+            )
+        ) == Decimal("34.2")
+
+        # Luna Rossa FTR [9.7], 9984569
+        # 10.8 > 34.7 < 160
+        assert _quantize(
+            WorldMainMapCalculators.step(
+                WorldPlayResult(
+                    play_rating=PlayResultCalculators.play_rating(9984569, 97),
+                    partner_step=160,
+                )
+            )
+        ) == Decimal("34.7")
+
+        # ultradiaxon-N3 FTR [10.5], 9349575
+        # 10.2 > 32.7 < 160
+        assert _quantize(
+            WorldMainMapCalculators.step(
+                WorldPlayResult(
+                    play_rating=PlayResultCalculators.play_rating(9349575, 105),
+                    partner_step=160,
+                )
+            )
+        ) == Decimal("32.7")
+
+        # san skia FTR [8.3], 10001036
+        # 10.3 > 64.2 < 310
+        assert _quantize(
+            WorldMainMapCalculators.step(
+                WorldPlayResult(
+                    play_rating=PlayResultCalculators.play_rating(10001036, 83),
+                    partner_step=310,
+                )
+            )
+        ) == Decimal("64.2")

tests/conftest.py

@@ -0,0 +1,53 @@
+import pytest
+from sqlalchemy import create_engine, text
+from sqlalchemy.orm import sessionmaker
+
+# region sqlalchemy fixtures
+engine = create_engine("sqlite:///:memory:")
+Session = sessionmaker()
+
+
+@pytest.fixture(scope="session")
+def db_conn():
+    conn = engine.connect()
+    yield conn
+    conn.close()
+
+
+@pytest.fixture()
+def db_session(db_conn):
+    session = Session(bind=db_conn)
+    yield session
+    session.close()
+
+    # drop everything
+    query_tables = db_conn.execute(
+        text("SELECT name FROM sqlite_master WHERE type='table'")
+    ).fetchall()
+    for row in query_tables:
+        table_name = row[0]
+        db_conn.execute(text(f"DROP TABLE {table_name}"))
+
+    query_views = db_conn.execute(
+        text("SELECT name FROM sqlite_master WHERE type='view'")
+    ).fetchall()
+    for row in query_views:
+        view_name = row[0]
+        db_conn.execute(text(f"DROP VIEW {view_name}"))
+
+    query_indexes = db_conn.execute(
+        text("SELECT name FROM sqlite_master WHERE type='index'")
+    ).fetchall()
+    for row in query_indexes:
+        index_name = row[0]
+        db_conn.execute(text(f"DROP INDEX {index_name}"))
+
+    query_triggers = db_conn.execute(
+        text("SELECT name FROM sqlite_master WHERE type='trigger'")
+    ).fetchall()
+    for row in query_triggers:
+        trigger_name = row[0]
+        db_conn.execute(text(f"DROP TRIGGER {trigger_name}"))
+
+
+# endregion

tests/db/models/test_custom_types.py

@@ -0,0 +1,67 @@
+from datetime import datetime, timedelta, timezone
+from enum import IntEnum
+from typing import Optional
+
+from sqlalchemy import text
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from arcaea_offline.database.models._custom_types import DbIntEnum, TZDateTime
+
+
+class TestIntEnum(IntEnum):
+    __test__ = False
+
+    ONE = 1
+    TWO = 2
+    THREE = 3
+
+
+class TestBase(DeclarativeBase):
+    __test__ = False
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+
+
+class IntEnumTestModel(TestBase):
+    __tablename__ = "test_int_enum"
+    value: Mapped[Optional[TestIntEnum]] = mapped_column(DbIntEnum(TestIntEnum))
+
+
+class TZDatetimeTestModel(TestBase):
+    __tablename__ = "test_tz_datetime"
+    value: Mapped[Optional[datetime]] = mapped_column(TZDateTime)
+
+
+class TestCustomTypes:
+    def test_int_enum(self, db_session):
+        def _query_value(_id: int):
+            return db_session.execute(
+                text(
+                    f"SELECT value FROM {IntEnumTestModel.__tablename__} WHERE id = {_id}"
+                )
+            ).one()[0]
+
+        TestBase.metadata.create_all(db_session.bind, checkfirst=False)
+
+        basic_obj = IntEnumTestModel(id=1, value=TestIntEnum.TWO)
+        null_obj = IntEnumTestModel(id=2, value=None)
+        db_session.add(basic_obj)
+        db_session.add(null_obj)
+        db_session.commit()
+
+        assert _query_value(1) == TestIntEnum.TWO.value
+        assert _query_value(2) is None
+
+    def test_tz_datetime(self, db_session):
+        TestBase.metadata.create_all(db_session.bind, checkfirst=False)
+
+        dt1 = datetime.now(tz=timezone(timedelta(hours=8)))
+
+        basic_obj = TZDatetimeTestModel(id=1, value=dt1)
+        null_obj = TZDatetimeTestModel(id=2, value=None)
+        db_session.add(basic_obj)
+        db_session.add(null_obj)
+        db_session.commit()
+
+        assert basic_obj.value == dt1
+        assert null_obj.value is None

tests/db/models/v4/test_songs.py

@@ -0,0 +1,108 @@
+from arcaea_offline.database.models.v4.songs import (
+    Chart,
+    ChartInfo,
+    Difficulty,
+    Pack,
+    Song,
+    SongsBase,
+    SongsViewBase,
+)
+
+
+def _song(**kw):
+    defaults = {"artist": "test"}
+    defaults.update(kw)
+    return Song(**defaults)
+
+
+def _difficulty(**kw):
+    defaults = {"rating_plus": False, "audio_override": False, "jacket_override": False}
+    defaults.update(kw)
+    return Difficulty(**defaults)
+
+
+class Test_Chart:
+    def init_db(self, session):
+        SongsBase.metadata.create_all(session.bind, checkfirst=False)
+        SongsViewBase.metadata.create_all(session.bind, checkfirst=False)
+
+    def test_chart_info(self, db_session):
+        self.init_db(db_session)
+
+        pre_entites = [
+            Pack(id="test", name="Test Pack"),
+            _song(idx=0, id="song0", set="test", title="Full Chart Info"),
+            _song(idx=1, id="song1", set="test", title="Partial Chart Info"),
+            _song(idx=2, id="song2", set="test", title="No Chart Info"),
+            _difficulty(song_id="song0", rating_class=2, rating=9),
+            _difficulty(song_id="song1", rating_class=2, rating=9),
+            _difficulty(song_id="song2", rating_class=2, rating=9),
+            ChartInfo(song_id="song0", rating_class=2, constant=90, notes=1234),
+            ChartInfo(song_id="song1", rating_class=2, constant=90),
+        ]
+
+        db_session.add_all(pre_entites)
+        db_session.commit()
+
+        chart_song0_ratingclass2 = (
+            db_session.query(Chart)
+            .where((Chart.song_id == "song0") & (Chart.rating_class == 2))
+            .one()
+        )
+
+        assert chart_song0_ratingclass2.constant == 90
+        assert chart_song0_ratingclass2.notes == 1234
+
+        chart_song1_ratingclass2 = (
+            db_session.query(Chart)
+            .where((Chart.song_id == "song1") & (Chart.rating_class == 2))
+            .one()
+        )
+
+        assert chart_song1_ratingclass2.constant == 90
+        assert chart_song1_ratingclass2.notes is None
+
+        chart_song2_ratingclass2 = (
+            db_session.query(Chart)
+            .where((Chart.song_id == "song2") & (Chart.rating_class == 2))
+            .first()
+        )
+
+        assert chart_song2_ratingclass2 is None
+
+    def test_difficulty_title_override(self, db_session):
+        self.init_db(db_session)
+
+        pre_entites = [
+            Pack(id="test", name="Test Pack"),
+            _song(idx=0, id="test", set="test", title="Test"),
+            _difficulty(song_id="test", rating_class=0, rating=2),
+            _difficulty(song_id="test", rating_class=1, rating=5),
+            _difficulty(song_id="test", rating_class=2, rating=8),
+            _difficulty(
+                song_id="test", rating_class=3, rating=10, title="TEST ~REVIVE~"
+            ),
+            ChartInfo(song_id="test", rating_class=0, constant=10),
+            ChartInfo(song_id="test", rating_class=1, constant=10),
+            ChartInfo(song_id="test", rating_class=2, constant=10),
+            ChartInfo(song_id="test", rating_class=3, constant=10),
+        ]
+
+        db_session.add_all(pre_entites)
+        db_session.commit()
+
+        charts_original_title = (
+            db_session.query(Chart)
+            .where((Chart.song_id == "test") & (Chart.rating_class in [0, 1, 2]))
+            .all()
+        )
+
+        assert all(chart.title == "Test" for chart in charts_original_title)
+
+        chart_overrided_title = (
+            db_session.query(Chart)
+            .where((Chart.song_id == "test") & (Chart.rating_class == 3))
+            .one()
+        )
+
+        assert chart_overrided_title.title == "TEST ~REVIVE~"

tests/db/models/v5/relationships/test_common.py

@@ -0,0 +1,143 @@
+"""
+Database model v5 common relationships
+
+┌──────┐   ┌──────┐   ┌────────────┐   ┌────────────┐
+│ Pack ◄───► Song ◄───► Difficulty ◄───┤ PlayResult │
+└──────┘   └──┬───┘   └─────▲──────┘   └────────────┘
+              │             │
+              │       ┌─────▼─────┐
+              └───────► ChartInfo │
+                      └───────────┘
+"""
+
+from arcaea_offline.constants.enums import ArcaeaRatingClass
+from arcaea_offline.database.models.v5 import (
+    ChartInfo,
+    Difficulty,
+    ModelsV5Base,
+    Pack,
+    PlayResult,
+    Song,
+)
+
+
+class TestSongRelationships:
+    @staticmethod
+    def init_db(session):
+        ModelsV5Base.metadata.create_all(session.bind)
+
+    def test_relationships(self, db_session):
+        self.init_db(db_session)
+
+        song_id = "test_song"
+        title_en = "Test Lorem Ipsum"
+        artist_en = "Test Artist"
+
+        pack = Pack(
+            id="test_pack",
+            name="Test Pack",
+            description="This is a test pack.",
+        )
+
+        song = Song(
+            idx=1,
+            id=song_id,
+            title=title_en,
+            artist=artist_en,
+            pack_id=pack.id,
+        )
+
+        difficulty_pst = Difficulty(
+            song_id=song.id,
+            rating_class=ArcaeaRatingClass.PAST,
+            rating=2,
+            rating_plus=False,
+        )
+        chart_info_pst = ChartInfo(
+            song_id=song.id,
+            rating_class=ArcaeaRatingClass.PAST,
+            constant=20,
+            notes=200,
+        )
+
+        difficulty_prs = Difficulty(
+            song_id=song.id,
+            rating_class=ArcaeaRatingClass.PRESENT,
+            rating=7,
+            rating_plus=True,
+        )
+        chart_info_prs = ChartInfo(
+            song_id=song.id,
+            rating_class=ArcaeaRatingClass.PRESENT,
+            constant=78,
+            notes=780,
+        )
+
+        difficulty_ftr = Difficulty(
+            song_id=song.id,
+            rating_class=ArcaeaRatingClass.FUTURE,
+            rating=10,
+            rating_plus=True,
+        )
+        chart_info_ftr = ChartInfo(
+            song_id=song.id,
+            rating_class=ArcaeaRatingClass.FUTURE,
+            constant=109,
+            notes=1090,
+        )
+
+        difficulty_etr = Difficulty(
+            song_id=song.id,
+            rating_class=ArcaeaRatingClass.ETERNAL,
+            rating=9,
+            rating_plus=True,
+        )
+
+        play_result_ftr = PlayResult(
+            song_id=song.id,
+            rating_class=ArcaeaRatingClass.FUTURE,
+            score=123456,
+        )
+
+        db_session.add_all(
+            [
+                pack,
+                song,
+                difficulty_pst,
+                chart_info_pst,
+                difficulty_prs,
+                chart_info_prs,
+                difficulty_ftr,
+                chart_info_ftr,
+                difficulty_etr,
+                play_result_ftr,
+            ]
+        )
+        db_session.commit()
+
+        assert pack.songs == [song]
+
+        assert song.pack == pack
+        assert song.difficulties == [
+            difficulty_pst,
+            difficulty_prs,
+            difficulty_ftr,
+            difficulty_etr,
+        ]
+        assert song.charts_info == [chart_info_pst, chart_info_prs, chart_info_ftr]
+
+        assert difficulty_pst.song == song
+        assert difficulty_prs.song == song
+        assert difficulty_ftr.song == song
+        assert difficulty_etr.song == song
+
+        assert difficulty_pst.chart_info == chart_info_pst
+        assert difficulty_prs.chart_info == chart_info_prs
+        assert difficulty_ftr.chart_info == chart_info_ftr
+        assert difficulty_etr.chart_info is None
+
+        assert chart_info_pst.difficulty == difficulty_pst
+        assert chart_info_prs.difficulty == difficulty_prs
+        assert chart_info_ftr.difficulty == difficulty_ftr
+
+        assert play_result_ftr.difficulty == difficulty_ftr

tests/db/models/v5/relationships/test_pack.py

@@ -0,0 +1,69 @@
+"""
+Database model v5 relationships
+
+Pack <> PackLocalized
+"""
+
+from arcaea_offline.constants.enums import ArcaeaLanguage
+from arcaea_offline.database.models.v5 import ModelsV5Base, Pack, PackLocalized
+
+
+class TestPackRelationships:
+    @staticmethod
+    def init_db(session):
+        ModelsV5Base.metadata.create_all(session.bind)
+
+    def test_localized_objects(self, db_session):
+        self.init_db(db_session)
+
+        pack_id = "test_pack"
+        name_en = "Test Pack"
+        description_en = "Travel through common database models\nfrom the unpopular framework 'Arcaea Offline'\ntogether with an ordinary partner '∅'."
+
+        pack = Pack(
+            id=pack_id,
+            name=name_en,
+            description=description_en,
+        )
+
+        pkid_ja = 1
+        description_ja = "普通のパートナー「∅」と一緒に、\n不人気フレームワーク「Arcaea Offline」より、\n一般的なデータベース・モデルを通過する。"
+        pack_localized_ja = PackLocalized(
+            pkid=pkid_ja,
+            id=pack_id,
+            lang=ArcaeaLanguage.JA.value,
+            name=None,
+            description=description_ja,
+        )
+
+        pkid_zh_hans = 2
+        description_zh_hans = "与平凡的「∅」一起，\n在没人用的「Arcaea Offline」框架里，\n一同探索随处可见的数据库模型。"
+        pack_localized_zh_hans = PackLocalized(
+            pkid=pkid_zh_hans,
+            id=pack_id,
+            lang=ArcaeaLanguage.ZH_HANS.value,
+            name=None,
+            description=description_zh_hans,
+        )
+
+        db_session.add_all([pack, pack_localized_ja])
+        db_session.commit()
+
+        assert len(pack.localized_objects) == len([pack_localized_ja])
+
+        assert pack_localized_ja.parent.description == pack.description
+
+        # relationships should be viewonly
+        new_pack = Pack(
+            id=f"{pack_id}_new",
+            name="NEW",
+            description="new new pack",
+        )
+        db_session.add(new_pack)
+
+        pack_localized_ja.parent = new_pack
+        pack.localized_objects.append(pack_localized_zh_hans)
+        db_session.commit()
+
+        assert pack_localized_ja.parent == pack
+        assert len(pack.localized_objects) == 1

tests/db/models/v5/test_chart.py

@@ -0,0 +1,110 @@
+"""
+Database models v5
+
+Chart functionalities
+- basic data handling
+- Difficulty song info overriding
+"""
+
+from arcaea_offline.constants.enums.arcaea import ArcaeaRatingClass
+from arcaea_offline.database.models.v5 import (
+    Chart,
+    ChartInfo,
+    Difficulty,
+    ModelsV5Base,
+    ModelsV5ViewBase,
+    Pack,
+    Song,
+)
+
+
+class TestChart:
+    def init_db(self, session):
+        ModelsV5Base.metadata.create_all(session.bind)
+        ModelsV5ViewBase.metadata.create_all(session.bind)
+
+    def test_basic(self, db_session):
+        self.init_db(db_session)
+
+        pack_id = "test_pack"
+        song_id = "test_song"
+        rating_class = ArcaeaRatingClass.FUTURE
+
+        pack = Pack(id=pack_id, name="Test Pack")
+        song = Song(
+            idx=2,
+            id=song_id,
+            title="~TEST~",
+            artist="~test~",
+            pack_id=pack_id,
+        )
+        difficulty = Difficulty(
+            song_id=song_id,
+            rating_class=rating_class,
+            rating=9,
+            rating_plus=True,
+        )
+        chart_info = ChartInfo(
+            song_id=song_id,
+            rating_class=rating_class,
+            constant=98,
+            notes=980,
+        )
+        db_session.add_all([pack, song, difficulty, chart_info])
+
+        chart: Chart = (
+            db_session.query(Chart)
+            .where((Chart.song_id == song_id) & (Chart.rating_class == rating_class))
+            .one()
+        )
+
+        # `song_id` and `rating_class` are guarded by the WHERE clause above
+        assert chart.song_idx == song.idx
+        assert chart.title == song.title
+        assert chart.artist == song.artist
+        assert chart.pack_id == song.pack_id
+        assert chart.rating == difficulty.rating
+        assert chart.rating_plus == difficulty.rating_plus
+        assert chart.constant == chart_info.constant
+        assert chart.notes == chart_info.notes
+
+    def test_difficulty_override(self, db_session):
+        self.init_db(db_session)
+
+        pack_id = "test_pack"
+        song_id = "test_song"
+        rating_class = ArcaeaRatingClass.FUTURE
+
+        pack = Pack(id=pack_id, name="Test Pack")
+        song = Song(
+            idx=2,
+            id=song_id,
+            title="~TEST~",
+            artist="~test~",
+            pack_id=pack_id,
+        )
+        difficulty = Difficulty(
+            song_id=song_id,
+            rating_class=rating_class,
+            rating=9,
+            rating_plus=True,
+            title="~TEST DIFF~",
+            artist="~diff~",
+        )
+        chart_info = ChartInfo(
+            song_id=song_id,
+            rating_class=rating_class,
+            constant=98,
+            notes=980,
+        )
+        db_session.add_all([pack, song, difficulty, chart_info])
+
+        chart: Chart = (
+            db_session.query(Chart)
+            .where((Chart.song_id == song_id) & (Chart.rating_class == rating_class))
+            .one()
+        )
+
+        assert chart.song_idx == song.idx
+        assert chart.title == difficulty.title
+        assert chart.artist == difficulty.artist

tests/external/importers/arcaea/test_st3.py

@@ -0,0 +1,56 @@
+import sqlite3
+from datetime import datetime
+from importlib.resources import files
+
+import pytest
+from arcaea_offline.constants.enums.arcaea import (
+    ArcaeaPlayResultClearType,
+    ArcaeaPlayResultModifier,
+    ArcaeaRatingClass,
+)
+from arcaea_offline.external.importers.arcaea.st3 import St3Parser
+
+import tests.resources
+
+
+class TestSt3Parser:
+    DB_PATH = files(tests.resources).joinpath("st3-test.db")
+
+    @property
+    def play_results(self):
+        conn = sqlite3.connect(str(self.DB_PATH))
+        return St3Parser.parse(conn)
+
+    def test_basic(self):
+        play_results = self.play_results
+
+        assert len(play_results) == 4
+
+        test1 = next(filter(lambda x: x.song_id == "test1", play_results))
+        assert test1.rating_class is ArcaeaRatingClass.FUTURE
+        assert test1.score == 9441167
+        assert test1.pure == 895
+        assert test1.far == 32
+        assert test1.lost == 22
+        assert test1.date == datetime.fromtimestamp(1722100000).astimezone()
+        assert test1.clear_type is ArcaeaPlayResultClearType.TRACK_LOST
+        assert test1.modifier is ArcaeaPlayResultModifier.HARD
+
+    def test_corrupt_handling(self):
+        play_results = self.play_results
+
+        corrupt1 = filter(lambda x: x.song_id == "corrupt1", play_results)
+        # `rating_class` out of range, so this should be ignored during parsing,
+        # thus does not present in the result.
+        assert len(list(corrupt1)) == 0
+
+        corrupt2 = next(filter(lambda x: x.song_id == "corrupt2", play_results))
+        assert corrupt2.clear_type is None
+        assert corrupt2.modifier is None
+
+        date1 = next(filter(lambda x: x.song_id == "date1", play_results))
+        assert date1.date is None
+
+    def test_invalid_input(self):
+        pytest.raises(TypeError, St3Parser.parse, "abcdefghijklmn")
+        pytest.raises(TypeError, St3Parser.parse, 123456)

tests/resources/st3-test.json

@@ -0,0 +1,117 @@
+{
+  "_comment": "A quick preview of the data in st3-test.db",
+  "scores": [
+    {
+      "id": 1,
+      "version": 1,
+      "score": 9441167,
+      "shinyPerfectCount": 753,
+      "perfectCount": 895,
+      "nearCount": 32,
+      "missCount": 22,
+      "date": 1722100000,
+      "songId": "test1",
+      "songDifficulty": 2,
+      "modifier": 2,
+      "health": 0,
+      "ct": 0
+    },
+    {
+      "id": 2,
+      "version": 1,
+      "score": 9752087,
+      "shinyPerfectCount": 914,
+      "perfectCount": 1024,
+      "nearCount": 29,
+      "missCount": 12,
+      "date": 1722200000,
+      "songId": "test2",
+      "songDifficulty": 2,
+      "modifier": 0,
+      "health": 100,
+      "ct": 0
+    },
+    {
+      "id": 3,
+      "version": 1,
+      "score": 9750000,
+      "shinyPerfectCount": 900,
+      "perfectCount": 1000,
+      "nearCount": 20,
+      "missCount": 10,
+      "date": 1722200000,
+      "songId": "corrupt1",
+      "songDifficulty": 5,
+      "modifier": 0,
+      "health": 0,
+      "ct": 0
+    },
+    {
+      "id": 4,
+      "version": 1,
+      "score": 9750000,
+      "shinyPerfectCount": 900,
+      "perfectCount": 1000,
+      "nearCount": 20,
+      "missCount": 10,
+      "date": 1722200000,
+      "songId": "corrupt2",
+      "songDifficulty": 2,
+      "modifier": 9,
+      "health": 0,
+      "ct": 0
+    },
+    {
+      "id": 5,
+      "version": 1,
+      "score": 9750000,
+      "shinyPerfectCount": 900,
+      "perfectCount": 1000,
+      "nearCount": 20,
+      "missCount": 10,
+      "date": 1,
+      "songId": "date1",
+      "songDifficulty": 2,
+      "modifier": 0,
+      "health": 0,
+      "ct": 0
+    }
+  ],
+  "cleartypes": [
+    {
+      "id": 1,
+      "songId": "test1",
+      "songDifficulty": 2,
+      "clearType": 0,
+      "ct": 0
+    },
+    {
+      "id": 2,
+      "songId": "test2",
+      "songDifficulty": 2,
+      "clearType": 1,
+      "ct": 0
+    },
+    {
+      "id": 3,
+      "songId": "corrupt1",
+      "songDifficulty": 5,
+      "clearType": 0,
+      "ct": 0
+    },
+    {
+      "id": 4,
+      "songId": "corrupt2",
+      "songDifficulty": 2,
+      "clearType": 7,
+      "ct": 0
+    },
+    {
+      "id": 5,
+      "songId": "date1",
+      "songDifficulty": 2,
+      "clearType": 1,
+      "ct": 0
+    }
+  ]
+}

tests/utils/test_formatters.py

@@ -0,0 +1,126 @@
+import pytest
+
+from arcaea_offline.constants.enums import (
+    ArcaeaPlayResultClearType,
+    ArcaeaPlayResultModifier,
+    ArcaeaRatingClass,
+)
+from arcaea_offline.utils.formatters.play_result import PlayResultFormatter
+from arcaea_offline.utils.formatters.rating_class import RatingClassFormatter
+
+
+class TestRatingClassFormatter:
+    def test_name(self):
+        assert RatingClassFormatter.name(ArcaeaRatingClass.PAST) == "Past"
+        assert RatingClassFormatter.name(ArcaeaRatingClass.PRESENT) == "Present"
+        assert RatingClassFormatter.name(ArcaeaRatingClass.FUTURE) == "Future"
+        assert RatingClassFormatter.name(ArcaeaRatingClass.BEYOND) == "Beyond"
+        assert RatingClassFormatter.name(ArcaeaRatingClass.ETERNAL) == "Eternal"
+
+        assert RatingClassFormatter.name(2) == "Future"
+
+        assert RatingClassFormatter.name(100) == "Unknown"
+        assert RatingClassFormatter.name(-1) == "Unknown"
+
+        pytest.raises(TypeError, RatingClassFormatter.name, "2")
+        pytest.raises(TypeError, RatingClassFormatter.name, [])
+        pytest.raises(TypeError, RatingClassFormatter.name, None)
+
+    def test_abbreviation(self):
+        assert RatingClassFormatter.abbreviation(ArcaeaRatingClass.PAST) == "PST"
+        assert RatingClassFormatter.abbreviation(ArcaeaRatingClass.PRESENT) == "PRS"
+        assert RatingClassFormatter.abbreviation(ArcaeaRatingClass.FUTURE) == "FTR"
+        assert RatingClassFormatter.abbreviation(ArcaeaRatingClass.BEYOND) == "BYD"
+        assert RatingClassFormatter.abbreviation(ArcaeaRatingClass.ETERNAL) == "ETR"
+
+        assert RatingClassFormatter.abbreviation(2) == "FTR"
+
+        assert RatingClassFormatter.abbreviation(100) == "UNK"
+        assert RatingClassFormatter.abbreviation(-1) == "UNK"
+
+        pytest.raises(TypeError, RatingClassFormatter.abbreviation, "2")
+        pytest.raises(TypeError, RatingClassFormatter.abbreviation, [])
+        pytest.raises(TypeError, RatingClassFormatter.abbreviation, None)
+
+
+class TestPlayResultFormatter:
+    def test_score_grade(self):
+        assert PlayResultFormatter.score_grade(10001284) == "EX+"
+        assert PlayResultFormatter.score_grade(9989210) == "EX+"
+        assert PlayResultFormatter.score_grade(9900000) == "EX+"
+
+        assert PlayResultFormatter.score_grade(9899999) == "EX"
+        assert PlayResultFormatter.score_grade(9843717) == "EX"
+        assert PlayResultFormatter.score_grade(9800000) == "EX"
+
+        assert PlayResultFormatter.score_grade(9799999) == "AA"
+        assert PlayResultFormatter.score_grade(9794015) == "AA"
+        assert PlayResultFormatter.score_grade(9750000) == "AA"
+
+        assert PlayResultFormatter.score_grade(9499999) == "A"
+        assert PlayResultFormatter.score_grade(9356855) == "A"
+        assert PlayResultFormatter.score_grade(9200000) == "A"
+
+        assert PlayResultFormatter.score_grade(9199999) == "B"
+        assert PlayResultFormatter.score_grade(9065785) == "B"
+        assert PlayResultFormatter.score_grade(8900000) == "B"
+
+        assert PlayResultFormatter.score_grade(8899999) == "C"
+        assert PlayResultFormatter.score_grade(8756211) == "C"
+        assert PlayResultFormatter.score_grade(8600000) == "C"
+
+        assert PlayResultFormatter.score_grade(8599999) == "D"
+        assert PlayResultFormatter.score_grade(5500000) == "D"
+        assert PlayResultFormatter.score_grade(0) == "D"
+
+        pytest.raises(ValueError, PlayResultFormatter.score_grade, -1)
+        pytest.raises(TypeError, PlayResultFormatter.score_grade, "10001284")
+        pytest.raises(TypeError, PlayResultFormatter.score_grade, [])
+        pytest.raises(TypeError, PlayResultFormatter.score_grade, None)
+
+    def test_clear_type(self):
+        assert (
+            PlayResultFormatter.clear_type(ArcaeaPlayResultClearType.TRACK_LOST)
+            == "TRACK LOST"
+        )
+        assert (
+            PlayResultFormatter.clear_type(ArcaeaPlayResultClearType.NORMAL_CLEAR)
+            == "NORMAL CLEAR"
+        )
+        assert (
+            PlayResultFormatter.clear_type(ArcaeaPlayResultClearType.FULL_RECALL)
+            == "FULL RECALL"
+        )
+        assert (
+            PlayResultFormatter.clear_type(ArcaeaPlayResultClearType.PURE_MEMORY)
+            == "PURE MEMORY"
+        )
+        assert (
+            PlayResultFormatter.clear_type(ArcaeaPlayResultClearType.EASY_CLEAR)
+            == "EASY CLEAR"
+        )
+        assert (
+            PlayResultFormatter.clear_type(ArcaeaPlayResultClearType.HARD_CLEAR)
+            == "HARD CLEAR"
+        )
+        assert PlayResultFormatter.clear_type(None) == "None"
+
+        assert PlayResultFormatter.clear_type(1) == "NORMAL CLEAR"
+        assert PlayResultFormatter.clear_type(6) == "UNKNOWN"
+
+        pytest.raises(ValueError, PlayResultFormatter.clear_type, -1)
+        pytest.raises(TypeError, PlayResultFormatter.clear_type, "1")
+        pytest.raises(TypeError, PlayResultFormatter.clear_type, [])
+
+    def test_modifier(self):
+        assert PlayResultFormatter.modifier(ArcaeaPlayResultModifier.NORMAL) == "NORMAL"
+        assert PlayResultFormatter.modifier(ArcaeaPlayResultModifier.EASY) == "EASY"
+        assert PlayResultFormatter.modifier(ArcaeaPlayResultModifier.HARD) == "HARD"
+        assert PlayResultFormatter.modifier(None) == "None"
+
+        assert PlayResultFormatter.modifier(1) == "EASY"
+        assert PlayResultFormatter.modifier(6) == "UNKNOWN"
+
+        pytest.raises(ValueError, PlayResultFormatter.modifier, -1)
+        pytest.raises(TypeError, PlayResultFormatter.modifier, "1")
+        pytest.raises(TypeError, PlayResultFormatter.modifier, [])

tox.ini

@@ -0,0 +1,16 @@
+[tox]
+env_list =
+    py311
+    py310
+    py39
+    py38
+minversion = 4.11.3
+
+[testenv]
+description = run the tests with pytest
+package = wheel
+wheel_build_env = .pkg
+deps =
+    pytest==7.4.3
+commands =
+    pytest {tty:--color=yes} {posargs}