diff --git a/LICENSE.txt b/LICENSE.txt index 261eeb9..a612ad9 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,201 +1,373 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +Mozilla Public License Version 2.0 +================================== + +1. Definitions +-------------- + +1.1. "Contributor" + means each individual or legal entity that creates, contributes to + the creation of, or owns Covered Software. + +1.2. "Contributor Version" + means the combination of the Contributions of others (if any) used + by a Contributor and that particular Contributor's Contribution. + +1.3. "Contribution" + means Covered Software of a particular Contributor. + +1.4. "Covered Software" + means Source Code Form to which the initial Contributor has attached + the notice in Exhibit A, the Executable Form of such Source Code + Form, and Modifications of such Source Code Form, in each case + including portions thereof. + +1.5. "Incompatible With Secondary Licenses" + means + + (a) that the initial Contributor has attached the notice described + in Exhibit B to the Covered Software; or + + (b) that the Covered Software was made available under the terms of + version 1.1 or earlier of the License, but not also under the + terms of a Secondary License. + +1.6. "Executable Form" + means any form of the work other than Source Code Form. + +1.7. "Larger Work" + means a work that combines Covered Software with other material, in + a separate file or files, that is not Covered Software. + +1.8. "License" + means this document. + +1.9. "Licensable" + means having the right to grant, to the maximum extent possible, + whether at the time of the initial grant or subsequently, any and + all of the rights conveyed by this License. + +1.10. "Modifications" + means any of the following: + + (a) any file in Source Code Form that results from an addition to, + deletion from, or modification of the contents of Covered + Software; or + + (b) any new file in Source Code Form that contains any Covered + Software. + +1.11. "Patent Claims" of a Contributor + means any patent claim(s), including without limitation, method, + process, and apparatus claims, in any patent Licensable by such + Contributor that would be infringed, but for the grant of the + License, by the making, using, selling, offering for sale, having + made, import, or transfer of either its Contributions or its + Contributor Version. + +1.12. "Secondary License" + means either the GNU General Public License, Version 2.0, the GNU + Lesser General Public License, Version 2.1, the GNU Affero General + Public License, Version 3.0, or any later versions of those + licenses. + +1.13. "Source Code Form" + means the form of the work preferred for making modifications. + +1.14. "You" (or "Your") + means an individual or a legal entity exercising rights under this + License. For legal entities, "You" includes any entity that + controls, is controlled by, or is under common control with You. For + purposes of this definition, "control" means (a) the power, direct + or indirect, to cause the direction or management of such entity, + whether by contract or otherwise, or (b) ownership of more than + fifty percent (50%) of the outstanding shares or beneficial + ownership of such entity. + +2. License Grants and Conditions +-------------------------------- + +2.1. Grants + +Each Contributor hereby grants You a world-wide, royalty-free, +non-exclusive license: + +(a) under intellectual property rights (other than patent or trademark) + Licensable by such Contributor to use, reproduce, make available, + modify, display, perform, distribute, and otherwise exploit its + Contributions, either on an unmodified basis, with Modifications, or + as part of a Larger Work; and + +(b) under Patent Claims of such Contributor to make, use, sell, offer + for sale, have made, import, and otherwise transfer either its + Contributions or its Contributor Version. + +2.2. Effective Date + +The licenses granted in Section 2.1 with respect to any Contribution +become effective for each Contribution on the date the Contributor first +distributes such Contribution. + +2.3. Limitations on Grant Scope + +The licenses granted in this Section 2 are the only rights granted under +this License. No additional rights or licenses will be implied from the +distribution or licensing of Covered Software under this License. +Notwithstanding Section 2.1(b) above, no patent license is granted by a +Contributor: + +(a) for any code that a Contributor has removed from Covered Software; + or + +(b) for infringements caused by: (i) Your and any other third party's + modifications of Covered Software, or (ii) the combination of its + Contributions with other software (except as part of its Contributor + Version); or + +(c) under Patent Claims infringed by Covered Software in the absence of + its Contributions. + +This License does not grant any rights in the trademarks, service marks, +or logos of any Contributor (except as may be necessary to comply with +the notice requirements in Section 3.4). + +2.4. Subsequent Licenses + +No Contributor makes additional grants as a result of Your choice to +distribute the Covered Software under a subsequent version of this +License (see Section 10.2) or under the terms of a Secondary License (if +permitted under the terms of Section 3.3). + +2.5. Representation + +Each Contributor represents that the Contributor believes its +Contributions are its original creation(s) or it has sufficient rights +to grant the rights to its Contributions conveyed by this License. + +2.6. Fair Use + +This License is not intended to limit any rights You have under +applicable copyright doctrines of fair use, fair dealing, or other +equivalents. + +2.7. Conditions + +Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted +in Section 2.1. + +3. Responsibilities +------------------- + +3.1. Distribution of Source Form + +All distribution of Covered Software in Source Code Form, including any +Modifications that You create or to which You contribute, must be under +the terms of this License. You must inform recipients that the Source +Code Form of the Covered Software is governed by the terms of this +License, and how they can obtain a copy of this License. You may not +attempt to alter or restrict the recipients' rights in the Source Code +Form. + +3.2. Distribution of Executable Form + +If You distribute Covered Software in Executable Form then: + +(a) such Covered Software must also be made available in Source Code + Form, as described in Section 3.1, and You must inform recipients of + the Executable Form how they can obtain a copy of such Source Code + Form by reasonable means in a timely manner, at a charge no more + than the cost of distribution to the recipient; and + +(b) You may distribute such Executable Form under the terms of this + License, or sublicense it under different terms, provided that the + license for the Executable Form does not attempt to limit or alter + the recipients' rights in the Source Code Form under this License. + +3.3. Distribution of a Larger Work + +You may create and distribute a Larger Work under terms of Your choice, +provided that You also comply with the requirements of this License for +the Covered Software. If the Larger Work is a combination of Covered +Software with a work governed by one or more Secondary Licenses, and the +Covered Software is not Incompatible With Secondary Licenses, this +License permits You to additionally distribute such Covered Software +under the terms of such Secondary License(s), so that the recipient of +the Larger Work may, at their option, further distribute the Covered +Software under the terms of either this License or such Secondary +License(s). + +3.4. Notices + +You may not remove or alter the substance of any license notices +(including copyright notices, patent notices, disclaimers of warranty, +or limitations of liability) contained within the Source Code Form of +the Covered Software, except that You may alter any license notices to +the extent required to remedy known factual inaccuracies. + +3.5. Application of Additional Terms + +You may choose to offer, and to charge a fee for, warranty, support, +indemnity or liability obligations to one or more recipients of Covered +Software. However, You may do so only on Your own behalf, and not on +behalf of any Contributor. You must make it absolutely clear that any +such warranty, support, indemnity, or liability obligation is offered by +You alone, and You hereby agree to indemnify every Contributor for any +liability incurred by such Contributor as a result of warranty, support, +indemnity or liability terms You offer. You may include additional +disclaimers of warranty and limitations of liability specific to any +jurisdiction. + +4. Inability to Comply Due to Statute or Regulation +--------------------------------------------------- + +If it is impossible for You to comply with any of the terms of this +License with respect to some or all of the Covered Software due to +statute, judicial order, or regulation then You must: (a) comply with +the terms of this License to the maximum extent possible; and (b) +describe the limitations and the code they affect. Such description must +be placed in a text file included with all distributions of the Covered +Software under this License. Except to the extent prohibited by statute +or regulation, such description must be sufficiently detailed for a +recipient of ordinary skill to be able to understand it. + +5. Termination +-------------- + +5.1. The rights granted under this License will terminate automatically +if You fail to comply with any of its terms. However, if You become +compliant, then the rights granted under this License from a particular +Contributor are reinstated (a) provisionally, unless and until such +Contributor explicitly and finally terminates Your grants, and (b) on an +ongoing basis, if such Contributor fails to notify You of the +non-compliance by some reasonable means prior to 60 days after You have +come back into compliance. Moreover, Your grants from a particular +Contributor are reinstated on an ongoing basis if such Contributor +notifies You of the non-compliance by some reasonable means, this is the +first time You have received notice of non-compliance with this License +from such Contributor, and You become compliant prior to 30 days after +Your receipt of the notice. + +5.2. If You initiate litigation against any entity by asserting a patent +infringement claim (excluding declaratory judgment actions, +counter-claims, and cross-claims) alleging that a Contributor Version +directly or indirectly infringes any patent, then the rights granted to +You by any and all Contributors for the Covered Software under Section +2.1 of this License shall terminate. + +5.3. In the event of termination under Sections 5.1 or 5.2 above, all +end user license agreements (excluding distributors and resellers) which +have been validly granted by You or Your distributors under this License +prior to termination shall survive termination. + +************************************************************************ +* * +* 6. Disclaimer of Warranty * +* ------------------------- * +* * +* Covered Software is provided under this License on an "as is" * +* basis, without warranty of any kind, either expressed, implied, or * +* statutory, including, without limitation, warranties that the * +* Covered Software is free of defects, merchantable, fit for a * +* particular purpose or non-infringing. The entire risk as to the * +* quality and performance of the Covered Software is with You. * +* Should any Covered Software prove defective in any respect, You * +* (not any Contributor) assume the cost of any necessary servicing, * +* repair, or correction. This disclaimer of warranty constitutes an * +* essential part of this License. No use of any Covered Software is * +* authorized under this License except under this disclaimer. * +* * +************************************************************************ + +************************************************************************ +* * +* 7. Limitation of Liability * +* -------------------------- * +* * +* Under no circumstances and under no legal theory, whether tort * +* (including negligence), contract, or otherwise, shall any * +* Contributor, or anyone who distributes Covered Software as * +* permitted above, be liable to You for any direct, indirect, * +* special, incidental, or consequential damages of any character * +* including, without limitation, damages for lost profits, loss of * +* goodwill, work stoppage, computer failure or malfunction, or any * +* and all other commercial damages or losses, even if such party * +* shall have been informed of the possibility of such damages. This * +* limitation of liability shall not apply to liability for death or * +* personal injury resulting from such party's negligence to the * +* extent applicable law prohibits such limitation. Some * +* jurisdictions do not allow the exclusion or limitation of * +* incidental or consequential damages, so this exclusion and * +* limitation may not apply to You. * +* * +************************************************************************ + +8. Litigation +------------- + +Any litigation relating to this License may be brought only in the +courts of a jurisdiction where the defendant maintains its principal +place of business and such litigation shall be governed by laws of that +jurisdiction, without reference to its conflict-of-law provisions. +Nothing in this Section shall prevent a party's ability to bring +cross-claims or counter-claims. + +9. Miscellaneous +---------------- + +This License represents the complete agreement concerning the subject +matter hereof. If any provision of this License is held to be +unenforceable, such provision shall be reformed only to the extent +necessary to make it enforceable. Any law or regulation which provides +that the language of a contract shall be construed against the drafter +shall not be used to construe this License against a Contributor. + +10. Versions of the License +--------------------------- + +10.1. New Versions + +Mozilla Foundation is the license steward. Except as provided in Section +10.3, no one other than the license steward has the right to modify or +publish new versions of this License. Each version will be given a +distinguishing version number. + +10.2. Effect of New Versions + +You may distribute the Covered Software under the terms of the version +of the License under which You originally received the Covered Software, +or under the terms of any subsequent version published by the license +steward. + +10.3. Modified Versions + +If you create software not governed by this License, and you want to +create a new license for such software, you may create and use a +modified version of this License if you rename the license and remove +any references to the name of the license steward (except to note that +such modified license differs from this License). + +10.4. Distributing Source Code Form that is Incompatible With Secondary +Licenses + +If You choose to distribute Source Code Form that is Incompatible With +Secondary Licenses under the terms of this version of the License, the +notice described in Exhibit B of this License must be attached. + +Exhibit A - Source Code Form License Notice +------------------------------------------- + + This Source Code Form is subject to the terms of the Mozilla Public + License, v. 2.0. If a copy of the MPL was not distributed with this + file, You can obtain one at http://mozilla.org/MPL/2.0/. + +If it is not possible or desirable to put the notice in a particular +file, then You may include the notice in a location (such as a LICENSE +file in a relevant directory) where a recipient would be likely to look +for such a notice. + +You may add additional accurate notices of copyright ownership. + +Exhibit B - "Incompatible With Secondary Licenses" Notice +--------------------------------------------------------- + + This Source Code Form is "Incompatible With Secondary Licenses", as + defined by the Mozilla Public License, v. 2.0. diff --git a/README.md b/README.md index 70a411d..a2e05d1 100644 --- a/README.md +++ b/README.md @@ -309,12 +309,51 @@ In order to provide full interoperability with NAIF, hifitime uses the NAIF algo # Changelog -## 4.0.0 (WIP) +## 4.0.0 -+ Minimum Support Rust Version (MSRV) bumped to 1.77.0 -+ Major refactoring of the code for ease of maintenance and removal of deprecrated functions from 3.x -+ Centralization of all time scale conversions into the `to_time_scale` function -- huge effort by [@gwbres](https://github.com/gwbres) -+ Removed `der` encoding/decoding for Epoch and Duration. +_This update is not mearly an iteration, but a redesign in how time scale are handled in hifitime, fixing nanosecond rounding errors, and improving the Python user experience. As of version 4.0.0, Hifitime is licensed under the Mozilla Public License version 2, refer to [discussion #274](https://github.com/nyx-space/hifitime/discussions/274) for details._ + +## Breaking changes + +* Refactor epoch to keep time in its own time scale by @gwbres and @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/280 +* Duration serde now human readable + Display of Epoch is now Gregorian in its initialization time scale by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/299 +* Improve error handling (switching to `snafu`) by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/300 +* Breaking change: renamed Julian date constants and removed other Julian date constants by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/307 +* Minimum Support Rust Version (MSRV) bumped to 1.77.0 + +_Note:_ as of version 4.0.0, dependency updates will increment the minor version. + +## New features / improvements + +* Support exceptions in Python by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/301 +* Add Python regression test for #249 by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/305 +* MJD/JDE UTC fix + `to_time_scale` now available in Python by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/332 +* Add Python datetime interop by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/333 +* Add autogenerated Kani harnesses by @cvick32 in https://github.com/nyx-space/hifitime/pull/316 +* Kani autogen follow on by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/318 + + +## Bug fixes + +* Fix bug in `to_gregorian_str` by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/308 +* Fix conversion to Gregorian by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/303 +* Rename `EpochError` to `HifitimeError` and add exception testing by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/315 +* Prevent rounding of the GNSS from nanoseconds initializers by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/319 +* Fix ceil with zero duration by @cardigan1008 in https://github.com/nyx-space/hifitime/pull/323 +* Fix token exceed in from_str() by @cardigan1008 in https://github.com/nyx-space/hifitime/pull/324 + + +The main change in this refactoring is that `Epoch`s now keep the time in their own time scales. This greatly simplifies conversion between time scales, and ensures that all computations happen in the same time scale as the initialization time scale, then no sub-nanosecond rounding error could be introduced. + +## Maintenance + +* Removed der dependency by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/297 +* Refactor epochrs as a module by @ChristopherRabotin in https://github.com/nyx-space/hifitime/pull/298 +* 4.0.0 dev gh 237 by @gwbres in https://github.com/nyx-space/hifitime/pull/289 +* Introduce doc_cfg and mark ut1 within ut1 crate feature by @gwbres in https://github.com/nyx-space/hifitime/pull/321 +* Update pyo3 requirement from 0.21.1 to 0.22.0 by @dependabot in https://github.com/nyx-space/hifitime/pull/312 +* Update tabled requirement from 0.15.0 to 0.16.0 by @dependabot in https://github.com/nyx-space/hifitime/pull/325 +* Update lexical-core requirement from 0.8.5 to 1.0.1 by @dependabot in https://github.com/nyx-space/hifitime/pull/330 ## 3.9.0 @@ -433,5 +472,15 @@ The exact steps should be: 1. Jump into the virtual environment: `source .venv/bin/activate` (e.g.) 1. Make sure pytest is installed: `pip install pytest` 1. Build hifitime specifying the output folder of the Python egg: `maturin build -F python --out dist` -1. Install the egg: `pip install dist/hifitime-4.0.0.dev1-cp311-cp311-linux_x86_64.whl` -1. Run the tests using the environmental pytest: `.venv/bin/pytest` \ No newline at end of file +1. Install the egg: `pip install dist/hifitime-4.0.0.alpha1-cp311-cp311-linux_x86_64.whl` +1. Run the tests using the environmental pytest: `.venv/bin/pytest` + +### Type hinting + +Hifitime uses the approach from [`dora`](https://github.com/dora-rs/dora/pull/493) to enable type hinting in IDEs. This approach requires running `maturin` twice: once to generate to the bindings and a second time for it to incorporate the `pyi` file. + +```bash +maturin develop -F python; +python generate_stubs.py hifitime hifitime.pyi; +maturin develop +``` \ No newline at end of file diff --git a/generate_stubs.py b/generate_stubs.py new file mode 100644 index 0000000..8da22cd --- /dev/null +++ b/generate_stubs.py @@ -0,0 +1,533 @@ +import argparse +import ast +import importlib +import inspect +import logging +import re +import subprocess +from functools import reduce +from typing import Any, Dict, List, Mapping, Optional, Set, Tuple, Union + + +def path_to_type(*elements: str) -> ast.AST: + base: ast.AST = ast.Name(id=elements[0], ctx=ast.Load()) + for e in elements[1:]: + base = ast.Attribute(value=base, attr=e, ctx=ast.Load()) + return base + + +OBJECT_MEMBERS = dict(inspect.getmembers(object)) +BUILTINS: Dict[str, Union[None, Tuple[List[ast.AST], ast.AST]]] = { + "__annotations__": None, + "__bool__": ([], path_to_type("bool")), + "__bytes__": ([], path_to_type("bytes")), + "__class__": None, + "__contains__": ([path_to_type("typing", "Any")], path_to_type("bool")), + "__del__": None, + "__delattr__": ([path_to_type("str")], path_to_type("None")), + "__delitem__": ([path_to_type("typing", "Any")], path_to_type("typing", "Any")), + "__dict__": None, + "__dir__": None, + "__doc__": None, + "__eq__": ([path_to_type("typing", "Any")], path_to_type("bool")), + "__format__": ([path_to_type("str")], path_to_type("str")), + "__ge__": ([path_to_type("typing", "Any")], path_to_type("bool")), + "__getattribute__": ([path_to_type("str")], path_to_type("typing", "Any")), + "__getitem__": ([path_to_type("typing", "Any")], path_to_type("typing", "Any")), + "__gt__": ([path_to_type("typing", "Any")], path_to_type("bool")), + "__hash__": ([], path_to_type("int")), + "__init__": ([], path_to_type("None")), + "__init_subclass__": None, + "__iter__": ([], path_to_type("typing", "Any")), + "__le__": ([path_to_type("typing", "Any")], path_to_type("bool")), + "__len__": ([], path_to_type("int")), + "__lt__": ([path_to_type("typing", "Any")], path_to_type("bool")), + "__module__": None, + "__ne__": ([path_to_type("typing", "Any")], path_to_type("bool")), + "__new__": None, + "__next__": ([], path_to_type("typing", "Any")), + "__int__": ([], path_to_type("None")), + "__reduce__": None, + "__reduce_ex__": None, + "__repr__": ([], path_to_type("str")), + "__setattr__": ( + [path_to_type("str"), path_to_type("typing", "Any")], + path_to_type("None"), + ), + "__setitem__": ( + [path_to_type("typing", "Any"), path_to_type("typing", "Any")], + path_to_type("typing", "Any"), + ), + "__sizeof__": None, + "__str__": ([], path_to_type("str")), + "__subclasshook__": None, +} + + +def module_stubs(module: Any) -> ast.Module: + types_to_import = {"typing"} + classes = [] + functions = [] + for member_name, member_value in inspect.getmembers(module): + element_path = [module.__name__, member_name] + if member_name.startswith("__"): + pass + elif member_name.startswith("DoraStatus"): + pass + elif inspect.isclass(member_value): + classes.append( + class_stubs(member_name, member_value, element_path, types_to_import) + ) + elif inspect.isbuiltin(member_value): + functions.append( + function_stub( + member_name, + member_value, + element_path, + types_to_import, + in_class=False, + ) + ) + else: + logging.warning(f"Unsupported root construction {member_name}") + return ast.Module( + body=[ast.Import(names=[ast.alias(name=t)]) for t in sorted(types_to_import)] + + classes + + functions, + type_ignores=[], + ) + + +def class_stubs( + cls_name: str, cls_def: Any, element_path: List[str], types_to_import: Set[str] +) -> ast.ClassDef: + attributes: List[ast.AST] = [] + methods: List[ast.AST] = [] + magic_methods: List[ast.AST] = [] + constants: List[ast.AST] = [] + for member_name, member_value in inspect.getmembers(cls_def): + current_element_path = [*element_path, member_name] + if member_name == "__init__" and "Error" not in cls_name: + try: + inspect.signature(cls_def) # we check it actually exists + methods = [ + function_stub( + member_name, + cls_def, + current_element_path, + types_to_import, + in_class=True, + ), + *methods, + ] + except ValueError as e: + if "no signature found" not in str(e): + raise ValueError( + f"Error while parsing signature of {cls_name}.__init_" + ) from e + elif ( + member_value == OBJECT_MEMBERS.get(member_name) + or BUILTINS.get(member_name, ()) is None + ): + pass + elif inspect.isdatadescriptor(member_value): + attributes.extend( + data_descriptor_stub( + member_name, member_value, current_element_path, types_to_import + ) + ) + elif inspect.isroutine(member_value): + (magic_methods if member_name.startswith("__") else methods).append( + function_stub( + member_name, + member_value, + current_element_path, + types_to_import, + in_class=True, + ) + ) + elif member_name == "__match_args__": + constants.append( + ast.AnnAssign( + target=ast.Name(id=member_name, ctx=ast.Store()), + annotation=ast.Subscript( + value=path_to_type("tuple"), + slice=ast.Tuple( + elts=[path_to_type("str"), ast.Ellipsis()], ctx=ast.Load() + ), + ctx=ast.Load(), + ), + value=ast.Constant(member_value), + simple=1, + ) + ) + elif member_value is not None: + constants.append( + ast.AnnAssign( + target=ast.Name(id=member_name, ctx=ast.Store()), + annotation=concatenated_path_to_type( + member_value.__class__.__name__, element_path, types_to_import + ), + value=ast.Ellipsis(), + simple=1, + ) + ) + else: + logging.warning( + f"Unsupported member {member_name} of class {'.'.join(element_path)}" + ) + + doc = inspect.getdoc(cls_def) + doc_comment = build_doc_comment(doc) if doc else None + return ast.ClassDef( + cls_name, + bases=[], + keywords=[], + body=( + ([doc_comment] if doc_comment else []) + + attributes + + methods + + magic_methods + + constants + ) + or [ast.Ellipsis()], + decorator_list=[path_to_type("typing", "final")], + ) + + +def data_descriptor_stub( + data_desc_name: str, + data_desc_def: Any, + element_path: List[str], + types_to_import: Set[str], +) -> Union[Tuple[ast.AnnAssign, ast.Expr], Tuple[ast.AnnAssign]]: + annotation = None + doc_comment = None + + doc = inspect.getdoc(data_desc_def) + if doc is not None: + annotation = returns_stub(data_desc_name, doc, element_path, types_to_import) + m = re.findall(r"^ *:return: *(.*) *$", doc, re.MULTILINE) + if len(m) == 1: + doc_comment = m[0] + elif len(m) > 1: + raise ValueError( + f"Multiple return annotations found with :return: in {'.'.join(element_path)} documentation" + ) + + assign = ast.AnnAssign( + target=ast.Name(id=data_desc_name, ctx=ast.Store()), + annotation=annotation or path_to_type("typing", "Any"), + simple=1, + ) + doc_comment = build_doc_comment(doc_comment) if doc_comment else None + return (assign, doc_comment) if doc_comment else (assign,) + + +def function_stub( + fn_name: str, + fn_def: Any, + element_path: List[str], + types_to_import: Set[str], + *, + in_class: bool, +) -> ast.FunctionDef: + body: List[ast.AST] = [] + doc = inspect.getdoc(fn_def) + if doc is not None: + doc_comment = build_doc_comment(doc) + if doc_comment is not None: + body.append(doc_comment) + + decorator_list = [] + if in_class and hasattr(fn_def, "__self__"): + decorator_list.append(ast.Name("staticmethod")) + + print(f"Documenting {fn_name}") + + return ast.FunctionDef( + fn_name, + arguments_stub(fn_name, fn_def, doc or "", element_path, types_to_import), + body or [ast.Ellipsis()], + decorator_list=decorator_list, + returns=( + returns_stub(fn_name, doc, element_path, types_to_import) if doc else None + ), + lineno=0, + ) + + +def arguments_stub( + callable_name: str, + callable_def: Any, + doc: str, + element_path: List[str], + types_to_import: Set[str], +) -> ast.arguments: + if "Error" in element_path[1]: + # Don't document errors + return ast.arguments(posonlyargs=[], args=[], defaults=[], kwonlyargs=[]) + + real_parameters: Mapping[str, inspect.Parameter] = inspect.signature( + callable_def + ).parameters + + if callable_name == "__init__": + real_parameters = { + "self": inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY), + **real_parameters, + } + + parsed_param_types = {} + optional_params = set() + + # Types for magic functions types + builtin = BUILTINS.get(callable_name) + if isinstance(builtin, tuple): + param_names = list(real_parameters.keys()) + if param_names and param_names[0] == "self": + del param_names[0] + for name, t in zip(param_names, builtin[0]): + parsed_param_types[name] = t + + elif callable_name in ["__add__", "__sub__", "__div__", "__mul__", "__radd__", "__rsub__", "__rdiv__", "__rmul__"]: + return ast.arguments(posonlyargs=[], args=[], defaults=[], kwonlyargs=[]) + + # Types from comment + for match in re.findall( + r"^ *:type *([a-zA-Z0-9_]+): ([^\n]*) *$", doc, re.MULTILINE + ): + if match[0] not in real_parameters: + raise ValueError( + f"The parameter {match[0]} of {'.'.join(element_path)} " + "is defined in the documentation but not in the function signature" + ) + type = match[1] + if type.endswith(", optional"): + optional_params.add(match[0]) + type = type[:-10] + parsed_param_types[match[0]] = convert_type_from_doc( + type, element_path, types_to_import + ) + + # we parse the parameters + posonlyargs = [] + args = [] + vararg = None + kwonlyargs = [] + kw_defaults = [] + kwarg = None + defaults = [] + for param in real_parameters.values(): + if param.name != "self" and param.name not in parsed_param_types: + raise ValueError( + f"The parameter {param.name} of {'.'.join(element_path)} " + "has no type definition in the function documentation" + ) + param_ast = ast.arg( + arg=param.name, annotation=parsed_param_types.get(param.name) + ) + + default_ast = None + if param.default != param.empty: + default_ast = ast.Constant(param.default) + if param.name not in optional_params: + raise ValueError( + f"Parameter {param.name} of {'.'.join(element_path)} " + "is optional according to the type but not flagged as such in the doc" + ) + elif param.name in optional_params: + raise ValueError( + f"Parameter {param.name} of {'.'.join(element_path)} " + "is optional according to the documentation but has no default value" + ) + + if param.kind == param.POSITIONAL_ONLY: + args.append(param_ast) + # posonlyargs.append(param_ast) + # defaults.append(default_ast) + elif param.kind == param.POSITIONAL_OR_KEYWORD: + args.append(param_ast) + defaults.append(default_ast) + elif param.kind == param.VAR_POSITIONAL: + vararg = param_ast + elif param.kind == param.KEYWORD_ONLY: + kwonlyargs.append(param_ast) + kw_defaults.append(default_ast) + elif param.kind == param.VAR_KEYWORD: + kwarg = param_ast + + return ast.arguments( + posonlyargs=posonlyargs, + args=args, + vararg=vararg, + kwonlyargs=kwonlyargs, + kw_defaults=kw_defaults, + defaults=defaults, + kwarg=kwarg, + ) + + +def returns_stub( + callable_name: str, doc: str, element_path: List[str], types_to_import: Set[str] +) -> Optional[ast.AST]: + if "Error" in element_path[1]: + # Don't document errors + return + + if callable_name in ["__add__", "__sub__", "__div__", "__mul__", "__radd__", "__rsub__", "__rdiv__", "__rmul__"]: + return + m = re.findall(r"^ *:rtype: *([^\n]*) *$", doc, re.MULTILINE) + if len(m) == 0: + builtin = BUILTINS.get(callable_name) + if isinstance(builtin, tuple) and builtin[1] is not None: + return builtin[1] + raise ValueError( + f"The return type of {'.'.join(element_path)} " + "has no type definition using :rtype: in the function documentation" + ) + if len(m) > 1: + raise ValueError( + f"Multiple return type annotations found with :rtype: for {'.'.join(element_path)}" + ) + return convert_type_from_doc(m[0], element_path, types_to_import) + + +def convert_type_from_doc( + type_str: str, element_path: List[str], types_to_import: Set[str] +) -> ast.AST: + type_str = type_str.strip() + return parse_type_to_ast(type_str, element_path, types_to_import) + + +def parse_type_to_ast( + type_str: str, element_path: List[str], types_to_import: Set[str] +) -> ast.AST: + # let's tokenize + tokens = [] + current_token = "" + for c in type_str: + if "a" <= c <= "z" or "A" <= c <= "Z" or c == ".": + current_token += c + else: + if current_token: + tokens.append(current_token) + current_token = "" + if c != " ": + tokens.append(c) + if current_token: + tokens.append(current_token) + + # let's first parse nested parenthesis + stack: List[List[Any]] = [[]] + for token in tokens: + if token == "[": + children: List[str] = [] + stack[-1].append(children) + stack.append(children) + elif token == "]": + stack.pop() + else: + stack[-1].append(token) + + # then it's easy + def parse_sequence(sequence: List[Any]) -> ast.AST: + # we split based on "or" + or_groups: List[List[str]] = [[]] + print(sequence) + # TODO: Fix sequence + if "Ros" in sequence and "2" in sequence: + sequence = ["".join(sequence)] + elif "dora.Ros" in sequence and "2" in sequence: + sequence = ["".join(sequence)] + + for e in sequence: + if e == "or": + or_groups.append([]) + else: + or_groups[-1].append(e) + if any(not g for g in or_groups): + raise ValueError( + f"Not able to parse type '{type_str}' used by {'.'.join(element_path)}" + ) + + new_elements: List[ast.AST] = [] + for group in or_groups: + if len(group) == 1 and isinstance(group[0], str): + new_elements.append( + concatenated_path_to_type(group[0], element_path, types_to_import) + ) + elif ( + len(group) == 2 + and isinstance(group[0], str) + and isinstance(group[1], list) + ): + new_elements.append( + ast.Subscript( + value=concatenated_path_to_type( + group[0], element_path, types_to_import + ), + slice=parse_sequence(group[1]), + ctx=ast.Load(), + ) + ) + else: + raise ValueError( + f"Not able to parse type '{type_str}' used by {'.'.join(element_path)}" + ) + return reduce( + lambda left, right: ast.BinOp(left=left, op=ast.BitOr(), right=right), + new_elements, + ) + + return parse_sequence(stack[0]) + + +def concatenated_path_to_type( + path: str, element_path: List[str], types_to_import: Set[str] +) -> ast.AST: + parts = path.split(".") + if any(not p for p in parts): + raise ValueError( + f"Not able to parse type '{path}' used by {'.'.join(element_path)}" + ) + if len(parts) > 1: + types_to_import.add(".".join(parts[:-1])) + return path_to_type(*parts) + + +def build_doc_comment(doc: str) -> Optional[ast.Expr]: + lines = [line.strip() for line in doc.split("\n")] + clean_lines = [] + for line in lines: + if line.startswith((":type", ":rtype")): + continue + clean_lines.append(line) + text = "\n".join(clean_lines).strip() + return ast.Expr(value=ast.Constant(text)) if text else None + + +def format_with_ruff(file: str) -> None: + subprocess.check_call(["python", "-m", "ruff", "format", file]) + + +if __name__ == "__main__": + parser = argparse.ArgumentParser( + description="Extract Python type stub from a python module." + ) + parser.add_argument( + "module_name", help="Name of the Python module for which generate stubs" + ) + parser.add_argument( + "out", + help="Name of the Python stub file to write to", + type=argparse.FileType("wt"), + ) + parser.add_argument( + "--ruff", help="Formats the generated stubs using Ruff", action="store_true" + ) + args = parser.parse_args() + stub_content = ast.unparse(module_stubs(importlib.import_module(args.module_name))) + args.out.write(stub_content) + if args.ruff: + format_with_ruff(args.out.name) diff --git a/hifitime.pyi b/hifitime.pyi new file mode 100644 index 0000000..537676c --- /dev/null +++ b/hifitime.pyi @@ -0,0 +1,1087 @@ +import typing + +@typing.final +class Duration: + """Defines generally usable durations for nanosecond precision valid for 32,768 centuries in either direction, and only on 80 bits / 10 octets. + +**Important conventions:** +1. The negative durations can be mentally modeled "BC" years. One hours before 01 Jan 0000, it was "-1" years but 365 days and 23h into the current day. +It was decided that the nanoseconds corresponds to the nanoseconds _into_ the current century. In other words, +a duration with centuries = -1 and nanoseconds = 0 is _a greater duration_ (further from zero) than centuries = -1 and nanoseconds = 1. +Duration zero minus one nanosecond returns a century of -1 and a nanosecond set to the number of nanoseconds in one century minus one. +That difference is exactly 1 nanoseconds, where the former duration is "closer to zero" than the latter. +As such, the largest negative duration that can be represented sets the centuries to i16::MAX and its nanoseconds to NANOSECONDS_PER_CENTURY. +2. It was also decided that opposite durations are equal, e.g. -15 minutes == 15 minutes. If the direction of time matters, use the signum function. + +(Python documentation hints)""" + + def __init__(self, string_repr: str) -> Duration: + """Defines generally usable durations for nanosecond precision valid for 32,768 centuries in either direction, and only on 80 bits / 10 octets. + +**Important conventions:** +1. The negative durations can be mentally modeled "BC" years. One hours before 01 Jan 0000, it was "-1" years but 365 days and 23h into the current day. +It was decided that the nanoseconds corresponds to the nanoseconds _into_ the current century. In other words, +a duration with centuries = -1 and nanoseconds = 0 is _a greater duration_ (further from zero) than centuries = -1 and nanoseconds = 1. +Duration zero minus one nanosecond returns a century of -1 and a nanosecond set to the number of nanoseconds in one century minus one. +That difference is exactly 1 nanoseconds, where the former duration is "closer to zero" than the latter. +As such, the largest negative duration that can be represented sets the centuries to i16::MAX and its nanoseconds to NANOSECONDS_PER_CENTURY. +2. It was also decided that opposite durations are equal, e.g. -15 minutes == 15 minutes. If the direction of time matters, use the signum function. + +(Python documentation hints)""" + + @staticmethod + def EPSILON():... + + @staticmethod + def MAX():... + + @staticmethod + def MIN():... + + @staticmethod + def MIN_NEGATIVE():... + + @staticmethod + def MIN_POSITIVE():... + + @staticmethod + def ZERO():... + + def abs(self) -> Duration: + """Returns the absolute value of this duration""" + + def approx(self) -> Duration: + """Rounds this duration to the largest units represented in this duration. + +This is useful to provide an approximate human duration. Under the hood, this function uses `round`, +so the "tipping point" of the rounding is half way to the next increment of the greatest unit. +As shown below, one example is that 35 hours and 59 minutes rounds to 1 day, but 36 hours and 1 minute rounds +to 2 days because 2 days is closer to 36h 1 min than 36h 1 min is to 1 day. + +# Example + +``` +use hifitime::{Duration, TimeUnits}; + +assert_eq!((2.hours() + 3.minutes()).approx(), 2.hours()); +assert_eq!((24.hours() + 3.minutes()).approx(), 1.days()); +assert_eq!((35.hours() + 59.minutes()).approx(), 1.days()); +assert_eq!((36.hours() + 1.minutes()).approx(), 2.days()); +assert_eq!((47.hours() + 3.minutes()).approx(), 2.days()); +assert_eq!((49.hours() + 3.minutes()).approx(), 2.days()); +```""" + + def ceil(self, duration: Duration) -> Duration: + """Ceils this duration to the closest provided duration + +This simply floors then adds the requested duration + +# Example +``` +use hifitime::{Duration, TimeUnits}; + +let two_hours_three_min = 2.hours() + 3.minutes(); +assert_eq!(two_hours_three_min.ceil(1.hours()), 3.hours()); +assert_eq!(two_hours_three_min.ceil(30.minutes()), 2.hours() + 30.minutes()); +assert_eq!(two_hours_three_min.ceil(4.hours()), 4.hours()); +assert_eq!(two_hours_three_min.ceil(1.seconds()), two_hours_three_min + 1.seconds()); +assert_eq!(two_hours_three_min.ceil(1.hours() + 5.minutes()), 2.hours() + 10.minutes()); +```""" + + def decompose(self) -> typing.Tuple: + """Decomposes a Duration in its sign, days, hours, minutes, seconds, ms, us, ns""" + + def floor(self, duration: Duration) -> Duration: + """Floors this duration to the closest duration from the bottom + +# Example +``` +use hifitime::{Duration, TimeUnits}; + +let two_hours_three_min = 2.hours() + 3.minutes(); +assert_eq!(two_hours_three_min.floor(1.hours()), 2.hours()); +assert_eq!(two_hours_three_min.floor(30.minutes()), 2.hours()); +// This is zero because we floor by a duration longer than the current duration, rounding it down +assert_eq!(two_hours_three_min.floor(4.hours()), 0.hours()); +assert_eq!(two_hours_three_min.floor(1.seconds()), two_hours_three_min); +assert_eq!(two_hours_three_min.floor(1.hours() + 1.minutes()), 2.hours() + 2.minutes()); +assert_eq!(two_hours_three_min.floor(1.hours() + 5.minutes()), 1.hours() + 5.minutes()); +```""" + + @staticmethod + def from_all_parts(sign: int, days: int, hours: int, minutes: int, seconds: int, milliseconds: int, microseconds: int, nanoseconds: int) -> Duration: + """Creates a new duration from its parts""" + + @staticmethod + def from_parts(centuries: int, nanoseconds: int) -> Duration: + """Create a normalized duration from its parts""" + + @staticmethod + def from_total_nanoseconds(nanos: int) -> Duration: + """Creates a new Duration from its full nanoseconds""" + + def is_negative(self) -> bool: + """Returns whether this is a negative or positive duration.""" + + def max(self, other: Duration) -> Duration: + """Returns the maximum of the two durations. + +``` +use hifitime::TimeUnits; + +let d0 = 20.seconds(); +let d1 = 21.seconds(); + +assert_eq!(d1, d1.max(d0)); +assert_eq!(d1, d0.max(d1)); +```""" + + def min(self, other: Duration) -> Duration: + """Returns the minimum of the two durations. + +``` +use hifitime::TimeUnits; + +let d0 = 20.seconds(); +let d1 = 21.seconds(); + +assert_eq!(d0, d1.min(d0)); +assert_eq!(d0, d0.min(d1)); +```""" + + def round(self, duration: Duration) -> Duration: + """Rounds this duration to the closest provided duration + +This performs both a `ceil` and `floor` and returns the value which is the closest to current one. +# Example +``` +use hifitime::{Duration, TimeUnits}; + +let two_hours_three_min = 2.hours() + 3.minutes(); +assert_eq!(two_hours_three_min.round(1.hours()), 2.hours()); +assert_eq!(two_hours_three_min.round(30.minutes()), 2.hours()); +assert_eq!(two_hours_three_min.round(4.hours()), 4.hours()); +assert_eq!(two_hours_three_min.round(1.seconds()), two_hours_three_min); +assert_eq!(two_hours_three_min.round(1.hours() + 5.minutes()), 2.hours() + 10.minutes()); +```""" + + def signum(self) -> int: + """Returns the sign of this duration ++ 0 if the number is zero ++ 1 if the number is positive ++ -1 if the number is negative""" + + def to_parts(self) -> typing.Tuple: + """Returns the centuries and nanoseconds of this duration +NOTE: These items are not public to prevent incorrect durations from being created by modifying the values of the structure directly.""" + + def to_seconds(self) -> float: + """Returns this duration in seconds f64. +For high fidelity comparisons, it is recommended to keep using the Duration structure.""" + + def to_unit(self, unit: Unit) -> float:... + + def total_nanoseconds(self) -> int: + """Returns the total nanoseconds in a signed 128 bit integer""" + + def __add__(): + """Return self+value.""" + + def __div__():... + + def __eq__(self, value: typing.Any) -> bool: + """Return self==value.""" + + def __ge__(self, value: typing.Any) -> bool: + """Return self>=value.""" + + def __getnewargs__(self):... + + def __gt__(self, value: typing.Any) -> bool: + """Return self>value.""" + + def __le__(self, value: typing.Any) -> bool: + """Return self<=value.""" + + def __lt__(self, value: typing.Any) -> bool: + """Return self bool: + """Return self!=value.""" + + def __radd__(): + """Return value+self.""" + + def __repr__(self) -> str: + """Return repr(self).""" + + def __rmul__(): + """Return value*self.""" + + def __rsub__(): + """Return value-self.""" + + def __str__(self) -> str: + """Return str(self).""" + + def __sub__(): + """Return self-value.""" + +@typing.final +class DurationError: + __cause__: typing.Any + __context__: typing.Any + __suppress_context__: typing.Any + __traceback__: typing.Any + args: typing.Any + + def add_note(): + """Exception.add_note(note) -- +add a note to the exception""" + + def with_traceback(): + """Exception.with_traceback(tb) -- +set self.__traceback__ to tb and return self.""" + + def __delattr__(): + """Implement delattr(self, name).""" + + def __getattribute__(): + """Return getattr(self, name).""" + + def __init__(): + """Initialize self. See help(type(self)) for accurate signature.""" + + def __repr__(): + """Return repr(self).""" + + def __setattr__(): + """Implement setattr(self, name, value).""" + + def __setstate__():... + + def __str__(): + """Return str(self).""" + +@typing.final +class Epoch: + """Defines a nanosecond-precision Epoch. + +Refer to the appropriate functions for initializing this Epoch from different time scales or representations. + +(Python documentation hints)""" + + def __init__(self, string_repr: str) -> Epoch: + """Defines a nanosecond-precision Epoch. + +Refer to the appropriate functions for initializing this Epoch from different time scales or representations. + +(Python documentation hints)""" + + def day_of_year(self) -> float: + """Returns the number of days since the start of the year.""" + + def duration_in_year(self) -> Duration: + """Returns the duration since the start of the year""" + + def hours(self) -> int: + """Returns the hours of the Gregorian representation of this epoch in the time scale it was initialized in.""" + + @staticmethod + def init_from_bdt_days(days: float) -> Epoch: + """Initialize an Epoch from the number of days since the BeiDou Time Epoch, +defined as January 1st 2006 (cf. ).""" + + @staticmethod + def init_from_bdt_nanoseconds(nanoseconds: float) -> Epoch: + """Initialize an Epoch from the number of days since the BeiDou Time Epoch, +defined as January 1st 2006 (cf. ). +This may be useful for time keeping devices that use BDT as a time source.""" + + @staticmethod + def init_from_bdt_seconds(seconds: float) -> Epoch: + """Initialize an Epoch from the number of seconds since the BeiDou Time Epoch, +defined as January 1st 2006 (cf. ).""" + + @staticmethod + def init_from_et_duration(duration_since_j2000: Duration) -> Epoch: + """Initialize an Epoch from the Ephemeris Time duration past 2000 JAN 01 (J2000 reference)""" + + @staticmethod + def init_from_et_seconds(seconds_since_j2000: float) -> Epoch: + """Initialize an Epoch from the Ephemeris Time seconds past 2000 JAN 01 (J2000 reference)""" + + @staticmethod + def init_from_gpst_days(days: float) -> Epoch: + """Initialize an Epoch from the number of days since the GPS Time Epoch, +defined as UTC midnight of January 5th to 6th 1980 (cf. ).""" + + @staticmethod + def init_from_gpst_nanoseconds(nanoseconds: float) -> Epoch: + """Initialize an Epoch from the number of nanoseconds since the GPS Time Epoch, +defined as UTC midnight of January 5th to 6th 1980 (cf. ). +This may be useful for time keeping devices that use GPS as a time source.""" + + @staticmethod + def init_from_gpst_seconds(seconds: float) -> Epoch: + """Initialize an Epoch from the number of seconds since the GPS Time Epoch, +defined as UTC midnight of January 5th to 6th 1980 (cf. ).""" + + @staticmethod + def init_from_gregorian(year: int, month: int, day: int, hour: int, minute: int, second: int, nanos: int, time_scale: TimeScale) -> Epoch: + """Initialize from the Gregorian parts""" + + @staticmethod + def init_from_gregorian_at_midnight(year: int, month: int, day: int, time_scale: TimeScale) -> Epoch: + """Initialize from the Gregorian parts, time set to midnight""" + + @staticmethod + def init_from_gregorian_at_noon(year: int, month: int, day: int, time_scale: TimeScale) -> Epoch: + """Initialize from the Gregorian parts, time set to noon""" + + @staticmethod + def init_from_gregorian_utc(year: int, month: int, day: int, hour: int, minute: int, second: int, nanos: int) -> Epoch: + """Builds an Epoch from the provided Gregorian date and time in TAI. If invalid date is provided, this function will panic. +Use maybe_from_gregorian_tai if unsure.""" + + @staticmethod + def init_from_gst_days(days: float) -> Epoch: + """Initialize an Epoch from the number of days since the Galileo Time Epoch, +starting on August 21st 1999 Midnight UT, +(cf. ).""" + + @staticmethod + def init_from_gst_nanoseconds(nanoseconds: float) -> Epoch: + """Initialize an Epoch from the number of nanoseconds since the Galileo Time Epoch, +starting on August 21st 1999 Midnight UT, +(cf. ). +This may be useful for time keeping devices that use GST as a time source.""" + + @staticmethod + def init_from_gst_seconds(seconds: float) -> Epoch: + """Initialize an Epoch from the number of seconds since the Galileo Time Epoch, +starting on August 21st 1999 Midnight UT, +(cf. ).""" + + @staticmethod + def init_from_jde_et(days: float) -> Epoch: + """Initialize from the JDE days""" + + @staticmethod + def init_from_jde_tai(days: float) -> Epoch: + """Initialize an Epoch from given JDE in TAI time scale""" + + @staticmethod + def init_from_jde_tdb(days: float) -> Epoch: + """Initialize from Dynamic Barycentric Time (TDB) (same as SPICE ephemeris time) in JD days""" + + @staticmethod + def init_from_jde_utc(days: float) -> Epoch: + """Initialize an Epoch from given JDE in UTC time scale""" + + @staticmethod + def init_from_mjd_tai(days: float) -> Epoch: + """Initialize an Epoch from given MJD in TAI time scale""" + + @staticmethod + def init_from_mjd_utc(days: float) -> Epoch: + """Initialize an Epoch from given MJD in UTC time scale""" + + @staticmethod + def init_from_qzsst_days(days: float) -> Epoch: + """Initialize an Epoch from the number of days since the QZSS Time Epoch, +defined as UTC midnight of January 5th to 6th 1980 (cf. ).""" + + @staticmethod + def init_from_qzsst_nanoseconds(nanoseconds: int) -> Epoch: + """Initialize an Epoch from the number of nanoseconds since the QZSS Time Epoch, +defined as UTC midnight of January 5th to 6th 1980 (cf. ). +This may be useful for time keeping devices that use QZSS as a time source.""" + + @staticmethod + def init_from_qzsst_seconds(seconds: float) -> Epoch: + """Initialize an Epoch from the number of seconds since the QZSS Time Epoch, +defined as UTC midnight of January 5th to 6th 1980 (cf. ).""" + + @staticmethod + def init_from_tai_days(days: float) -> Epoch: + """Initialize an Epoch from the provided TAI days since 1900 January 01 at midnight""" + + @staticmethod + def init_from_tai_duration(duration: Duration) -> Epoch: + """Creates a new Epoch from a Duration as the time difference between this epoch and TAI reference epoch.""" + + @staticmethod + def init_from_tai_parts(centuries: int, nanoseconds: int) -> Epoch: + """Creates a new Epoch from its centuries and nanosecond since the TAI reference epoch.""" + + @staticmethod + def init_from_tai_seconds(seconds: float) -> Epoch: + """Initialize an Epoch from the provided TAI seconds since 1900 January 01 at midnight""" + + @staticmethod + def init_from_tdb_duration(duration_since_j2000: Duration) -> Epoch: + """Initialize from Dynamic Barycentric Time (TDB) (same as SPICE ephemeris time) whose epoch is 2000 JAN 01 noon TAI.""" + + @staticmethod + def init_from_tdb_seconds(seconds_j2000: float) -> Epoch: + """Initialize an Epoch from Dynamic Barycentric Time (TDB) seconds past 2000 JAN 01 midnight (difference than SPICE) +NOTE: This uses the ESA algorithm, which is a notch more complicated than the SPICE algorithm, but more precise. +In fact, SPICE algorithm is precise +/- 30 microseconds for a century whereas ESA algorithm should be exactly correct.""" + + @staticmethod + def init_from_tt_duration(duration: Duration) -> Epoch: + """Initialize an Epoch from the provided TT seconds (approximated to 32.184s delta from TAI)""" + + @staticmethod + def init_from_tt_seconds(seconds: float) -> Epoch: + """Initialize an Epoch from the provided TT seconds (approximated to 32.184s delta from TAI)""" + + @staticmethod + def init_from_unix_milliseconds(milliseconds: float) -> Epoch: + """Initialize an Epoch from the provided UNIX millisecond timestamp since UTC midnight 1970 January 01.""" + + @staticmethod + def init_from_unix_seconds(seconds: float) -> Epoch: + """Initialize an Epoch from the provided UNIX second timestamp since UTC midnight 1970 January 01.""" + + @staticmethod + def init_from_utc_days(days: float) -> Epoch: + """Initialize an Epoch from the provided UTC days since 1900 January 01 at midnight""" + + @staticmethod + def init_from_utc_seconds(seconds: float) -> Epoch: + """Initialize an Epoch from the provided UTC seconds since 1900 January 01 at midnight""" + + def isoformat(self) -> str: + """Equivalent to `datetime.isoformat`, and truncated to 23 chars, refer to for format options""" + + def leap_seconds(self, iers_only: bool) -> float: + """Get the accumulated number of leap seconds up to this Epoch accounting only for the IERS leap seconds and the SOFA scaling from 1960 to 1972, depending on flag. +Returns None if the epoch is before 1960, year at which UTC was defined. + +# Why does this function return an `Option` when the other returns a value +This is to match the `iauDat` function of SOFA (src/dat.c). That function will return a warning and give up if the start date is before 1960.""" + + def leap_seconds_iers(self) -> int: + """Get the accumulated number of leap seconds up to this Epoch accounting only for the IERS leap seconds.""" + + def leap_seconds_with_file(self, iers_only: bool, provider: LeapSecondsFile) -> float: + """Get the accumulated number of leap seconds up to this Epoch from the provided LeapSecondProvider. +Returns None if the epoch is before 1960, year at which UTC was defined. + +# Why does this function return an `Option` when the other returns a value +This is to match the `iauDat` function of SOFA (src/dat.c). That function will return a warning and give up if the start date is before 1960.""" + + def microseconds(self) -> int: + """Returns the microseconds of the Gregorian representation of this epoch in the time scale it was initialized in.""" + + def milliseconds(self) -> int: + """Returns the milliseconds of the Gregorian representation of this epoch in the time scale it was initialized in.""" + + def minutes(self) -> int: + """Returns the minutes of the Gregorian representation of this epoch in the time scale it was initialized in.""" + + def month_name(self) -> MonthName:... + + def nanoseconds(self) -> int: + """Returns the nanoseconds of the Gregorian representation of this epoch in the time scale it was initialized in.""" + + def seconds(self) -> int: + """Returns the seconds of the Gregorian representation of this epoch in the time scale it was initialized in.""" + + def strftime(self, format_str: str) -> str: + """Equivalent to `datetime.strftime`, refer to for format options""" + + @staticmethod + def strptime(epoch_str: str, format_str: str) -> Epoch: + """Equivalent to `datetime.strptime`, refer to for format options""" + + @staticmethod + def system_now() -> Epoch: + """Returns the computer clock in UTC""" + + def timedelta(self, other: Duration) -> Duration: + """Differences between two epochs""" + + def to_bdt_days(self) -> float: + """Returns days past BDT (BeiDou) Time Epoch, defined as Jan 01 2006 UTC +(cf. ).""" + + def to_bdt_duration(self) -> Duration: + """Returns `Duration` past BDT (BeiDou) time Epoch.""" + + def to_bdt_nanoseconds(self) -> int: + """Returns nanoseconds past BDT (BeiDou) Time Epoch, defined as Jan 01 2006 UTC +(cf. ). +NOTE: This function will return an error if the centuries past GST time are not zero.""" + + def to_bdt_seconds(self) -> float: + """Returns seconds past BDT (BeiDou) Time Epoch""" + + def to_duration_in_time_scale(self, ts: TimeScale) -> Duration: + """Returns this epoch with respect to the provided time scale. +This is needed to correctly perform duration conversions in dynamical time scales (e.g. TDB).""" + + def to_et_centuries_since_j2000(self) -> float: + """Returns the number of centuries since Ephemeris Time (ET) J2000 (used for Archinal et al. rotations)""" + + def to_et_days_since_j2000(self) -> float: + """Returns the number of days since Ephemeris Time (ET) J2000 (used for Archinal et al. rotations)""" + + def to_et_duration(self) -> Duration: + """Returns the duration between J2000 and the current epoch as per NAIF SPICE. + +# Warning +The et2utc function of NAIF SPICE will assume that there are 9 leap seconds before 01 JAN 1972, +as this date introduces 10 leap seconds. At the time of writing, this does _not_ seem to be in +line with IERS and the documentation in the leap seconds list. + +In order to match SPICE, the as_et_duration() function will manually get rid of that difference.""" + + def to_et_seconds(self) -> float: + """Returns the Ephemeris Time seconds past 2000 JAN 01 midnight, matches NASA/NAIF SPICE.""" + + def to_gpst_days(self) -> float: + """Returns days past GPS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ).""" + + def to_gpst_duration(self) -> Duration: + """Returns `Duration` past GPS time Epoch.""" + + def to_gpst_nanoseconds(self) -> int: + """Returns nanoseconds past GPS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ). +NOTE: This function will return an error if the centuries past GPST time are not zero.""" + + def to_gpst_seconds(self) -> float: + """Returns seconds past GPS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ).""" + + def to_gst_days(self) -> float: + """Returns days past GST (Galileo) Time Epoch, +starting on August 21st 1999 Midnight UT +(cf. ).""" + + def to_gst_duration(self) -> Duration: + """Returns `Duration` past GST (Galileo) time Epoch.""" + + def to_gst_nanoseconds(self) -> int: + """Returns nanoseconds past GST (Galileo) Time Epoch, starting on August 21st 1999 Midnight UT +(cf. ). +NOTE: This function will return an error if the centuries past GST time are not zero.""" + + def to_gst_seconds(self) -> float: + """Returns seconds past GST (Galileo) Time Epoch""" + + def to_isoformat(self) -> str: + """The standard ISO format of this epoch (six digits of subseconds) in the _current_ time scale, refer to for format options.""" + + def to_jde_et(self, unit: Unit) -> float:... + + def to_jde_et_days(self) -> float: + """Returns the Ephemeris Time JDE past epoch""" + + def to_jde_et_duration(self) -> Duration:... + + def to_jde_tai(self, unit: Unit) -> float: + """Returns the Julian Days from epoch 01 Jan -4713 12:00 (noon) in desired Duration::Unit""" + + def to_jde_tai_days(self) -> float: + """Returns the Julian days from epoch 01 Jan -4713, 12:00 (noon) +as explained in "Fundamentals of astrodynamics and applications", Vallado et al. +4th edition, page 182, and on [Wikipedia](https://en.wikipedia.org/wiki/Julian_day).""" + + def to_jde_tai_duration(self) -> Duration: + """Returns the Julian Days from epoch 01 Jan -4713 12:00 (noon) as a Duration""" + + def to_jde_tai_seconds(self) -> float: + """Returns the Julian seconds in TAI.""" + + def to_jde_tdb_days(self) -> float: + """Returns the Dynamic Barycentric Time (TDB) (higher fidelity SPICE ephemeris time) whose epoch is 2000 JAN 01 noon TAI (cf. )""" + + def to_jde_tdb_duration(self) -> Duration:... + + def to_jde_tt_days(self) -> float: + """Returns days past Julian epoch in Terrestrial Time (TT) (previously called Terrestrial Dynamical Time (TDT))""" + + def to_jde_tt_duration(self) -> Duration:... + + def to_jde_utc_days(self) -> float: + """Returns the Julian days in UTC.""" + + def to_jde_utc_duration(self) -> Duration: + """Returns the Julian days in UTC as a `Duration`""" + + def to_jde_utc_seconds(self) -> float: + """Returns the Julian Days in UTC seconds.""" + + def to_mjd_tai(self, unit: Unit) -> float: + """Returns this epoch as a duration in the requested units in MJD TAI""" + + def to_mjd_tai_days(self) -> float: + """`as_mjd_days` creates an Epoch from the provided Modified Julian Date in days as explained +[here](http://tycho.usno.navy.mil/mjd.html). MJD epoch is Modified Julian Day at 17 November 1858 at midnight.""" + + def to_mjd_tai_seconds(self) -> float: + """Returns the Modified Julian Date in seconds TAI.""" + + def to_mjd_tt_days(self) -> float: + """Returns days past Modified Julian epoch in Terrestrial Time (TT) (previously called Terrestrial Dynamical Time (TDT))""" + + def to_mjd_tt_duration(self) -> Duration:... + + def to_mjd_utc(self, unit: Unit) -> float: + """Returns the Modified Julian Date in the provided unit in UTC.""" + + def to_mjd_utc_days(self) -> float: + """Returns the Modified Julian Date in days UTC.""" + + def to_mjd_utc_seconds(self) -> float: + """Returns the Modified Julian Date in seconds UTC.""" + + def to_nanoseconds_in_time_scale(self, time_scale: TimeScale) -> int: + """Attempts to return the number of nanoseconds since the reference epoch of the provided time scale. +This will return an overflow error if more than one century has past since the reference epoch in the provided time scale. +If this is _not_ an issue, you should use `epoch.to_duration_in_time_scale().to_parts()` to retrieve both the centuries and the nanoseconds +in that century.""" + + def to_qzsst_days(self) -> float: + """Returns days past QZSS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ).""" + + def to_qzsst_duration(self) -> Duration: + """Returns `Duration` past QZSS time Epoch.""" + + def to_qzsst_nanoseconds(self) -> int: + """Returns nanoseconds past QZSS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ). +NOTE: This function will return an error if the centuries past QZSST time are not zero.""" + + def to_qzsst_seconds(self) -> float: + """Returns seconds past QZSS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ).""" + + def to_rfc3339(self) -> str: + """Returns this epoch in UTC in the RFC3339 format""" + + def to_tai(self, unit: Unit) -> float: + """Returns the epoch as a floating point value in the provided unit""" + + def to_tai_days(self) -> float: + """Returns the number of days since J1900 in TAI""" + + def to_tai_duration(self) -> Duration: + """Returns this time in a Duration past J1900 counted in TAI""" + + def to_tai_parts(self) -> typing.Tuple: + """Returns the TAI parts of this duration""" + + def to_tai_seconds(self) -> float: + """Returns the number of TAI seconds since J1900""" + + def to_tdb_centuries_since_j2000(self) -> float: + """Returns the number of centuries since Dynamic Barycentric Time (TDB) J2000 (used for Archinal et al. rotations)""" + + def to_tdb_days_since_j2000(self) -> float: + """Returns the number of days since Dynamic Barycentric Time (TDB) J2000 (used for Archinal et al. rotations)""" + + def to_tdb_duration(self) -> Duration: + """Returns the Dynamics Barycentric Time (TDB) as a high precision Duration since J2000 + +## Algorithm +Given the embedded sine functions in the equation to compute the difference between TDB and TAI from the number of TDB seconds +past J2000, one cannot solve the revert the operation analytically. Instead, we iterate until the value no longer changes. + +1. Assume that the TAI duration is in fact the TDB seconds from J2000. +2. Offset to J2000 because `Epoch` stores everything in the J1900 but the TDB duration is in J2000. +3. Compute the offset `g` due to the TDB computation with the current value of the TDB seconds (defined in step 1). +4. Subtract that offset to the latest TDB seconds and store this as a new candidate for the true TDB seconds value. +5. Compute the difference between this candidate and the previous one. If the difference is less than one nanosecond, stop iteration. +6. Set the new candidate as the TDB seconds since J2000 and loop until step 5 breaks the loop, or we've done five iterations. +7. At this stage, we have a good approximation of the TDB seconds since J2000. +8. Reverse the algorithm given that approximation: compute the `g` offset, compute the difference between TDB and TAI, add the TT offset (32.184 s), and offset by the difference between J1900 and J2000.""" + + def to_tdb_seconds(self) -> float: + """Returns the Dynamic Barycentric Time (TDB) (higher fidelity SPICE ephemeris time) whose epoch is 2000 JAN 01 noon TAI (cf. )""" + + def to_time_scale(self, ts: TimeScale) -> Epoch: + """Converts self to another time scale + +As per the [Rust naming convention](https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv), +this borrows an Epoch and returns an owned Epoch.""" + + def to_tt_centuries_j2k(self) -> float: + """Returns the centuries passed J2000 TT""" + + def to_tt_days(self) -> float: + """Returns days past TAI epoch in Terrestrial Time (TT) (previously called Terrestrial Dynamical Time (TDT))""" + + def to_tt_duration(self) -> Duration: + """Returns `Duration` past TAI epoch in Terrestrial Time (TT).""" + + def to_tt_seconds(self) -> float: + """Returns seconds past TAI epoch in Terrestrial Time (TT) (previously called Terrestrial Dynamical Time (TDT))""" + + def to_tt_since_j2k(self) -> Duration: + """Returns the duration past J2000 TT""" + + def to_unix(self, unit: Unit) -> float: + """Returns the duration since the UNIX epoch in the provided unit.""" + + def to_unix_days(self) -> float: + """Returns the number days since the UNIX epoch defined 01 Jan 1970 midnight UTC.""" + + def to_unix_duration(self) -> Duration: + """Returns the Duration since the UNIX epoch UTC midnight 01 Jan 1970.""" + + def to_unix_milliseconds(self) -> float: + """Returns the number milliseconds since the UNIX epoch defined 01 Jan 1970 midnight UTC.""" + + def to_unix_seconds(self) -> float: + """Returns the number seconds since the UNIX epoch defined 01 Jan 1970 midnight UTC.""" + + def to_utc(self, unit: Unit) -> float: + """Returns the number of UTC seconds since the TAI epoch""" + + def to_utc_days(self) -> float: + """Returns the number of UTC days since the TAI epoch""" + + def to_utc_duration(self) -> Duration: + """Returns this time in a Duration past J1900 counted in UTC""" + + def to_utc_seconds(self) -> float: + """Returns the number of UTC seconds since the TAI epoch""" + + def year(self) -> int: + """Returns the number of Gregorian years of this epoch in the current time scale.""" + + def year_days_of_year(self) -> typing.Tuple: + """Returns the year and the days in the year so far (days of year).""" + + def __add__(): + """Return self+value.""" + + def __eq__(self, value: typing.Any) -> bool: + """Return self==value.""" + + def __ge__(self, value: typing.Any) -> bool: + """Return self>=value.""" + + def __getnewargs__(self):... + + def __gt__(self, value: typing.Any) -> bool: + """Return self>value.""" + + def __le__(self, value: typing.Any) -> bool: + """Return self<=value.""" + + def __lt__(self, value: typing.Any) -> bool: + """Return self bool: + """Return self!=value.""" + + def __radd__(): + """Return value+self.""" + + def __repr__(self) -> str: + """Return repr(self).""" + + def __rsub__(): + """Return value-self.""" + + def __str__(self) -> str: + """Return str(self).""" + + def __sub__(): + """Return self-value.""" + +@typing.final +class HifitimeError: + __cause__: typing.Any + __context__: typing.Any + __suppress_context__: typing.Any + __traceback__: typing.Any + args: typing.Any + + def add_note(): + """Exception.add_note(note) -- +add a note to the exception""" + + def with_traceback(): + """Exception.with_traceback(tb) -- +set self.__traceback__ to tb and return self.""" + + def __delattr__(): + """Implement delattr(self, name).""" + + def __getattribute__(): + """Return getattr(self, name).""" + + def __init__(): + """Initialize self. See help(type(self)) for accurate signature.""" + + def __repr__(): + """Return repr(self).""" + + def __setattr__(): + """Implement setattr(self, name, value).""" + + def __setstate__():... + + def __str__(): + """Return str(self).""" + +@typing.final +class LatestLeapSeconds: + """List of leap seconds from https://www.ietf.org/timezones/data/leap-seconds.list . +This list corresponds the number of seconds in TAI to the UTC offset and to whether it was an announced leap second or not. +The unannoucned leap seconds come from dat.c in the SOFA library.""" + + def __init__(self) -> None: + """List of leap seconds from https://www.ietf.org/timezones/data/leap-seconds.list . +This list corresponds the number of seconds in TAI to the UTC offset and to whether it was an announced leap second or not. +The unannoucned leap seconds come from dat.c in the SOFA library.""" + + def __repr__(self) -> str: + """Return repr(self).""" + +@typing.final +class LeapSecondsFile: + """A leap second provider that uses an IERS formatted leap seconds file. + +(Python documentation hints)""" + + def __init__(self, path: str) -> LeapSecondsFile: + """A leap second provider that uses an IERS formatted leap seconds file. + +(Python documentation hints)""" + + def __repr__(self) -> str: + """Return repr(self).""" + +@typing.final +class MonthName: + + def __eq__(self, value: typing.Any) -> bool: + """Return self==value.""" + + def __ge__(self, value: typing.Any) -> bool: + """Return self>=value.""" + + def __gt__(self, value: typing.Any) -> bool: + """Return self>value.""" + + def __int__(self) -> None: + """int(self)""" + + def __le__(self, value: typing.Any) -> bool: + """Return self<=value.""" + + def __lt__(self, value: typing.Any) -> bool: + """Return self bool: + """Return self!=value.""" + + def __repr__(self) -> str: + """Return repr(self).""" + April: MonthName = ... + August: MonthName = ... + December: MonthName = ... + February: MonthName = ... + January: MonthName = ... + July: MonthName = ... + June: MonthName = ... + March: MonthName = ... + May: MonthName = ... + November: MonthName = ... + October: MonthName = ... + September: MonthName = ... + +@typing.final +class ParsingError: + __cause__: typing.Any + __context__: typing.Any + __suppress_context__: typing.Any + __traceback__: typing.Any + args: typing.Any + + def add_note(): + """Exception.add_note(note) -- +add a note to the exception""" + + def with_traceback(): + """Exception.with_traceback(tb) -- +set self.__traceback__ to tb and return self.""" + + def __delattr__(): + """Implement delattr(self, name).""" + + def __getattribute__(): + """Return getattr(self, name).""" + + def __init__(): + """Initialize self. See help(type(self)) for accurate signature.""" + + def __repr__(): + """Return repr(self).""" + + def __setattr__(): + """Implement setattr(self, name, value).""" + + def __setstate__():... + + def __str__(): + """Return str(self).""" + +@typing.final +class TimeScale: + """Enum of the different time systems available""" + + def uses_leap_seconds(self) -> bool: + """Returns true if self takes leap seconds into account""" + + def __eq__(self, value: typing.Any) -> bool: + """Return self==value.""" + + def __ge__(self, value: typing.Any) -> bool: + """Return self>=value.""" + + def __gt__(self, value: typing.Any) -> bool: + """Return self>value.""" + + def __int__(self) -> None: + """int(self)""" + + def __le__(self, value: typing.Any) -> bool: + """Return self<=value.""" + + def __lt__(self, value: typing.Any) -> bool: + """Return self bool: + """Return self!=value.""" + + def __repr__(self) -> str: + """Return repr(self).""" + BDT: TimeScale = ... + ET: TimeScale = ... + GPST: TimeScale = ... + GST: TimeScale = ... + QZSST: TimeScale = ... + TAI: TimeScale = ... + TDB: TimeScale = ... + TT: TimeScale = ... + UTC: TimeScale = ... + +@typing.final +class TimeSeries: + """An iterator of a sequence of evenly spaced Epochs. + +(Python documentation hints)""" + + def __init__(self, start: Epoch, end: Epoch, step: Duration, inclusive: bool) -> TimeSeries: + """An iterator of a sequence of evenly spaced Epochs. + +(Python documentation hints)""" + + def __eq__(self, value: typing.Any) -> bool: + """Return self==value.""" + + def __ge__(self, value: typing.Any) -> bool: + """Return self>=value.""" + + def __getnewargs__(self):... + + def __gt__(self, value: typing.Any) -> bool: + """Return self>value.""" + + def __iter__(self) -> typing.Any: + """Implement iter(self).""" + + def __le__(self, value: typing.Any) -> bool: + """Return self<=value.""" + + def __lt__(self, value: typing.Any) -> bool: + """Return self bool: + """Return self!=value.""" + + def __next__(self) -> typing.Any: + """Implement next(self).""" + + def __repr__(self) -> str: + """Return repr(self).""" + + def __str__(self) -> str: + """Return str(self).""" + +@typing.final +class Unit: + """An Enum to perform time unit conversions.""" + + def from_seconds(self):... + + def in_seconds(self):... + + def __add__(): + """Return self+value.""" + + def __eq__(self, value: typing.Any) -> bool: + """Return self==value.""" + + def __ge__(self, value: typing.Any) -> bool: + """Return self>=value.""" + + def __gt__(self, value: typing.Any) -> bool: + """Return self>value.""" + + def __int__(self) -> None: + """int(self)""" + + def __le__(self, value: typing.Any) -> bool: + """Return self<=value.""" + + def __lt__(self, value: typing.Any) -> bool: + """Return self bool: + """Return self!=value.""" + + def __radd__(): + """Return value+self.""" + + def __repr__(self) -> str: + """Return repr(self).""" + + def __rmul__(): + """Return value*self.""" + + def __rsub__(): + """Return value-self.""" + + def __sub__(): + """Return self-value.""" + Century: Unit = ... + Day: Unit = ... + Hour: Unit = ... + Microsecond: Unit = ... + Millisecond: Unit = ... + Minute: Unit = ... + Nanosecond: Unit = ... + Second: Unit = ... + Week: Unit = ... + +@typing.final +class Ut1Provider: + """A structure storing all of the TAI-UT1 data""" + + def __init__(self) -> None: + """A structure storing all of the TAI-UT1 data""" + + def __repr__(self) -> str: + """Return repr(self).""" \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index add9841..4573985 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,5 @@ [build-system] -requires = ["maturin>=1.5,<1.6"] +requires = ["maturin>=1.6,<1.7"] build-backend = "maturin" [project] diff --git a/src/duration/kani_verif.rs b/src/duration/kani_verif.rs index 78c26f9..733b729 100644 --- a/src/duration/kani_verif.rs +++ b/src/duration/kani_verif.rs @@ -1,9 +1,9 @@ /* -* Hifitime, part of the Nyx Space tools -* Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) -* This Source Code Form is subject to the terms of the Apache -* v. 2.0. If a copy of the Apache License was not distributed with this -* file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Documentation: https://nyxspace.com/ */ diff --git a/src/duration/mod.rs b/src/duration/mod.rs index 40a2a8b..74f4a35 100644 --- a/src/duration/mod.rs +++ b/src/duration/mod.rs @@ -1,9 +1,9 @@ /* -* Hifitime, part of the Nyx Space tools -* Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) -* This Source Code Form is subject to the terms of the Apache -* v. 2.0. If a copy of the Apache License was not distributed with this -* file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Documentation: https://nyxspace.com/ */ @@ -63,6 +63,10 @@ pub mod ops; /// That difference is exactly 1 nanoseconds, where the former duration is "closer to zero" than the latter. /// As such, the largest negative duration that can be represented sets the centuries to i16::MAX and its nanoseconds to NANOSECONDS_PER_CENTURY. /// 2. It was also decided that opposite durations are equal, e.g. -15 minutes == 15 minutes. If the direction of time matters, use the signum function. +/// +/// (Python documentation hints) +/// :type string_repr: str +/// :rtype: Duration #[derive(Clone, Copy, Debug, PartialOrd, Eq, Ord)] #[repr(C)] #[cfg_attr(feature = "python", pyclass)] diff --git a/src/duration/ops.rs b/src/duration/ops.rs index 0d3f235..cdcc980 100644 --- a/src/duration/ops.rs +++ b/src/duration/ops.rs @@ -1,9 +1,9 @@ /* -* Hifitime, part of the Nyx Space tools -* Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) -* This Source Code Form is subject to the terms of the Apache -* v. 2.0. If a copy of the Apache License was not distributed with this -* file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Documentation: https://nyxspace.com/ */ diff --git a/src/duration/parse.rs b/src/duration/parse.rs index 8df9be3..7c09927 100644 --- a/src/duration/parse.rs +++ b/src/duration/parse.rs @@ -1,9 +1,9 @@ /* -* Hifitime, part of the Nyx Space tools -* Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) -* This Source Code Form is subject to the terms of the Apache -* v. 2.0. If a copy of the Apache License was not distributed with this -* file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Documentation: https://nyxspace.com/ */ diff --git a/src/duration/python.rs b/src/duration/python.rs index 5576c4d..da334ff 100644 --- a/src/duration/python.rs +++ b/src/duration/python.rs @@ -1,9 +1,9 @@ /* -* Hifitime, part of the Nyx Space tools -* Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) -* This Source Code Form is subject to the terms of the Apache -* v. 2.0. If a copy of the Apache License was not distributed with this -* file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Documentation: https://nyxspace.com/ */ @@ -22,12 +22,14 @@ impl Duration { #[must_use] /// Returns the centuries and nanoseconds of this duration /// NOTE: These items are not public to prevent incorrect durations from being created by modifying the values of the structure directly. + /// :rtype: typing.Tuple #[pyo3(name = "to_parts")] pub const fn py_to_parts(&self) -> (i16, u64) { (self.centuries, self.nanoseconds) } /// Returns the total nanoseconds in a signed 128 bit integer + /// :rtype: int #[pyo3(name = "total_nanoseconds")] pub fn py_total_nanoseconds(&self) -> i128 { self.total_nanoseconds() @@ -35,17 +37,21 @@ impl Duration { /// Returns this duration in seconds f64. /// For high fidelity comparisons, it is recommended to keep using the Duration structure. + /// :rtype: float #[pyo3(name = "to_seconds")] pub fn py_to_seconds(&self) -> f64 { self.to_seconds() } + /// :type unit: Unit + /// :rtype: float #[pyo3(name = "to_unit")] pub fn py_to_unit(&self, unit: Unit) -> f64 { self.to_unit(unit) } /// Returns the absolute value of this duration + /// :rtype: Duration #[pyo3(name = "abs")] pub fn py_abs(&self) -> Self { self.abs() @@ -55,12 +61,15 @@ impl Duration { /// + 0 if the number is zero /// + 1 if the number is positive /// + -1 if the number is negative + /// :rtype: int #[pyo3(name = "signum")] pub const fn py_signum(&self) -> i8 { self.signum() } /// Decomposes a Duration in its sign, days, hours, minutes, seconds, ms, us, ns + /// + /// :rtype: typing.Tuple #[pyo3(name = "decompose")] pub fn py_decompose(&self) -> (i8, u64, u64, u64, u64, u64, u64, u64) { self.decompose() @@ -81,6 +90,9 @@ impl Duration { /// assert_eq!(two_hours_three_min.floor(1.hours() + 1.minutes()), 2.hours() + 2.minutes()); /// assert_eq!(two_hours_three_min.floor(1.hours() + 5.minutes()), 1.hours() + 5.minutes()); /// ``` + /// + /// :type duration: Duration + /// :rtype: Duration #[pyo3(name = "floor")] pub fn py_floor(&self, duration: Self) -> Self { self.floor(duration) @@ -101,6 +113,9 @@ impl Duration { /// assert_eq!(two_hours_three_min.ceil(1.seconds()), two_hours_three_min + 1.seconds()); /// assert_eq!(two_hours_three_min.ceil(1.hours() + 5.minutes()), 2.hours() + 10.minutes()); /// ``` + /// + /// :type duration: Duration + /// :rtype: Duration #[pyo3(name = "ceil")] pub fn py_ceil(&self, duration: Self) -> Self { self.ceil(duration) @@ -120,6 +135,9 @@ impl Duration { /// assert_eq!(two_hours_three_min.round(1.seconds()), two_hours_three_min); /// assert_eq!(two_hours_three_min.round(1.hours() + 5.minutes()), 2.hours() + 10.minutes()); /// ``` + /// + /// :type duration: Duration + /// :rtype: Duration #[pyo3(name = "round")] pub fn py_round(&self, duration: Self) -> Self { self.round(duration) @@ -144,6 +162,8 @@ impl Duration { /// assert_eq!((47.hours() + 3.minutes()).approx(), 2.days()); /// assert_eq!((49.hours() + 3.minutes()).approx(), 2.days()); /// ``` + /// + /// :rtype: Duration #[pyo3(name = "approx")] pub fn py_approx(&self) -> Self { self.approx() @@ -160,6 +180,9 @@ impl Duration { /// assert_eq!(d0, d1.min(d0)); /// assert_eq!(d0, d0.min(d1)); /// ``` + /// + /// :type other: Duration + /// :rtype: Duration #[pyo3(name = "min")] pub fn py_min(&self, other: Self) -> Self { *(self.min(&other)) @@ -176,12 +199,16 @@ impl Duration { /// assert_eq!(d1, d1.max(d0)); /// assert_eq!(d1, d0.max(d1)); /// ``` + /// + /// :type other: Duration + /// :rtype: Duration #[pyo3(name = "max")] pub fn py_max(&self, other: Self) -> Self { *(self.max(&other)) } /// Returns whether this is a negative or positive duration. + /// :rtype: bool #[pyo3(name = "is_negative")] pub fn py_is_negative(&self) -> bool { self.is_negative() @@ -203,22 +230,81 @@ impl Duration { format!("{self} @ {self:p}") } + /// # Addition of Durations + /// Durations are centered on zero duration. Of the tuple, only the centuries may be negative, the nanoseconds are always positive + /// and represent the nanoseconds _into_ the current centuries. + /// + /// ## Examples + /// + `Duration { centuries: 0, nanoseconds: 1 }` is a positive duration of zero centuries and one nanosecond. + /// + `Duration { centuries: -1, nanoseconds: 1 }` is a negative duration representing "one century before zero minus one nanosecond" + /// + /// + /// :type other: hifitime.Duration + /// :rtype: Duration fn __add__(&self, other: Self) -> Duration { *self + other } + /// # Subtraction + /// This operation is a notch confusing with negative durations. + /// As described in the `Duration` structure, a Duration of (-1, NANOSECONDS_PER_CENTURY-1) is closer to zero + /// than (-1, 0). + /// + /// ## Algorithm + /// + /// ### A > B, and both are positive + /// + /// If A > B, then A.centuries is subtracted by B.centuries, and A.nanoseconds is subtracted by B.nanoseconds. + /// If an overflow occurs, e.g. A.nanoseconds < B.nanoseconds, the number of nanoseconds is increased by the number of nanoseconds per century, + /// and the number of centuries is decreased by one. + /// + /// ### A < B, and both are positive + /// + /// In this case, the resulting duration will be negative. The number of centuries is a signed integer, so it is set to the difference of A.centuries - B.centuries. + /// The number of nanoseconds however must be wrapped by the number of nanoseconds per century. + /// For example:, let A = (0, 1) and B = (1, 10), then the resulting duration will be (-2, NANOSECONDS_PER_CENTURY - (10 - 1)). In this case, the centuries are set + /// to -2 because B is _two_ centuries into the future (the number of centuries into the future is zero-indexed). + /// + /// ### A > B, both are negative + /// + /// In this case, we try to stick to normal arithmatics: (-9 - -10) = (-9 + 10) = +1. + /// In this case, we can simply add the components of the duration together. + /// For example, let A = (-1, NANOSECONDS_PER_CENTURY - 2), and B = (-1, NANOSECONDS_PER_CENTURY - 1). Respectively, A is _two_ nanoseconds _before_ Duration::ZERO + /// and B is _one_ nanosecond before Duration::ZERO. Then, A-B should be one nanoseconds before zero, i.e. (-1, NANOSECONDS_PER_CENTURY - 1). + /// This is because we _subtract_ "negative one nanosecond" from a "negative minus two nanoseconds", which corresponds to _adding_ the opposite, and the + /// opposite of "negative one nanosecond" is "positive one nanosecond". + /// + /// ### A < B, both are negative + /// + /// Just like in the prior case, we try to stick to normal arithmatics: (-10 - -9) = (-10 + 9) = -1. + /// + /// ### MIN is the minimum + /// + /// One cannot subtract anything from the MIN. + /// + /// ``` + /// from hifitime import Duration + /// + /// one_ns = Duration.from_parts(0, 1) + /// assert Duration.MIN() - one_ns == Duration.MIN() + /// ``` + /// + /// :rtype: hifitime.Duration fn __sub__(&self, other: Self) -> Duration { *self - other } + /// :rtype: hifitime.Duration fn __mul__(&self, other: f64) -> Duration { *self * other } + /// :rtype: hifitime.Duration fn __div__(&self, other: f64) -> Duration { *self / other } + /// :rtype: bool fn __richcmp__(&self, other: Self, op: CompareOp) -> bool { match op { CompareOp::Lt => *self < other, @@ -275,11 +361,23 @@ impl Duration { #[classmethod] #[pyo3(name = "from_parts")] /// Create a normalized duration from its parts + /// :type centuries: int + /// :type nanoseconds: int + /// :rtype: Duration fn py_from_parts(_cls: &Bound<'_, PyType>, centuries: i16, nanoseconds: u64) -> Self { Self::from_parts(centuries, nanoseconds) } /// Creates a new duration from its parts + /// :type sign: int + /// :type days: int + /// :type hours: int + /// :type minutes: int + /// :type seconds: int + /// :type milliseconds: int + /// :type microseconds: int + /// :type nanoseconds: int + /// :rtype: Duration #[allow(clippy::too_many_arguments)] #[classmethod] #[pyo3(name = "from_all_parts")] @@ -306,6 +404,9 @@ impl Duration { ) } + /// Creates a new Duration from its full nanoseconds + /// :type nanos: int + /// :rtype: Duration #[classmethod] #[pyo3(name = "from_total_nanoseconds")] fn py_from_total_nanoseconds(_cls: &Bound<'_, PyType>, nanos: i128) -> Self { diff --git a/src/duration/std.rs b/src/duration/std.rs index 9780f1b..055ee12 100644 --- a/src/duration/std.rs +++ b/src/duration/std.rs @@ -1,9 +1,9 @@ /* -* Hifitime, part of the Nyx Space tools -* Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) -* This Source Code Form is subject to the terms of the Apache -* v. 2.0. If a copy of the Apache License was not distributed with this -* file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Documentation: https://nyxspace.com/ */ diff --git a/src/efmt/consts.rs b/src/efmt/consts.rs index ef45f01..72e7d41 100644 --- a/src/efmt/consts.rs +++ b/src/efmt/consts.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use super::format::Format; use super::formatter::Item; diff --git a/src/efmt/format.rs b/src/efmt/format.rs index c04572e..abe72b8 100644 --- a/src/efmt/format.rs +++ b/src/efmt/format.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use snafu::ResultExt; diff --git a/src/efmt/formatter.rs b/src/efmt/formatter.rs index 0166935..cd9b08f 100644 --- a/src/efmt/formatter.rs +++ b/src/efmt/formatter.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use core::fmt; diff --git a/src/efmt/kani_verif.rs b/src/efmt/kani_verif.rs index 43bcb4c..0c30541 100644 --- a/src/efmt/kani_verif.rs +++ b/src/efmt/kani_verif.rs @@ -1,3 +1,13 @@ +/* +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ + use super::{ format::Format, formatter::{Formatter, Item}, diff --git a/src/efmt/mod.rs b/src/efmt/mod.rs index 4838056..b389afc 100644 --- a/src/efmt/mod.rs +++ b/src/efmt/mod.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ pub mod consts; pub mod format; diff --git a/src/epoch/formatting.rs b/src/epoch/formatting.rs index 14ac3c9..20a2a9c 100644 --- a/src/epoch/formatting.rs +++ b/src/epoch/formatting.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use core::fmt; diff --git a/src/epoch/gregorian.rs b/src/epoch/gregorian.rs index 233f7ab..1c6aff7 100644 --- a/src/epoch/gregorian.rs +++ b/src/epoch/gregorian.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use crate::errors::DurationError; use crate::parser::Token; diff --git a/src/epoch/initializers.rs b/src/epoch/initializers.rs index c503dd6..2abf5c2 100644 --- a/src/epoch/initializers.rs +++ b/src/epoch/initializers.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use core::str::FromStr; diff --git a/src/epoch/kani_verif.rs b/src/epoch/kani_verif.rs index 8da1953..6d2e4a6 100644 --- a/src/epoch/kani_verif.rs +++ b/src/epoch/kani_verif.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use crate::epoch::system_time::duration_since_unix_epoch; use crate::leap_seconds::LeapSecond; diff --git a/src/epoch/leap_seconds.rs b/src/epoch/leap_seconds.rs index 8e63876..8c0508a 100644 --- a/src/epoch/leap_seconds.rs +++ b/src/epoch/leap_seconds.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ #[cfg(feature = "python")] use pyo3::prelude::*; diff --git a/src/epoch/leap_seconds_file.rs b/src/epoch/leap_seconds_file.rs index dcba9d6..d463890 100644 --- a/src/epoch/leap_seconds_file.rs +++ b/src/epoch/leap_seconds_file.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ #[cfg(feature = "python")] use pyo3::prelude::*; @@ -24,6 +24,10 @@ use crate::{ #[cfg_attr(feature = "python", pyclass)] #[derive(Clone, Debug, Default)] /// A leap second provider that uses an IERS formatted leap seconds file. +/// +/// (Python documentation hints) +/// :type path: str +/// :rtype: LeapSecondsFile pub struct LeapSecondsFile { data: Vec, iter_pos: usize, diff --git a/src/epoch/mod.rs b/src/epoch/mod.rs index 90e868e..788bd46 100644 --- a/src/epoch/mod.rs +++ b/src/epoch/mod.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ mod formatting; mod gregorian; @@ -75,6 +75,10 @@ pub const NAIF_K: f64 = 1.657e-3; /// Defines a nanosecond-precision Epoch. /// /// Refer to the appropriate functions for initializing this Epoch from different time scales or representations. +/// +/// (Python documentation hints) +/// :type string_repr: str +/// :rtype: Epoch #[cfg_attr(kani, derive(kani::Arbitrary))] #[derive(Copy, Clone, Default, Eq)] #[repr(C)] @@ -169,6 +173,9 @@ impl Epoch { /// /// As per the [Rust naming convention](https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv), /// this borrows an Epoch and returns an owned Epoch. + /// + /// :type ts: TimeScale + /// :rtype: Epoch pub fn to_time_scale(&self, ts: TimeScale) -> Self { if ts == self.time_scale { // Do nothing, just return a copy @@ -290,6 +297,7 @@ impl Epoch { #[must_use] /// Get the accumulated number of leap seconds up to this Epoch accounting only for the IERS leap seconds. + /// :rtype: int pub fn leap_seconds_iers(&self) -> i32 { match self.leap_seconds(true) { Some(v) => v as i32, @@ -302,6 +310,8 @@ impl Epoch { /// /// # Why does this function return an `Option` when the other returns a value /// This is to match the `iauDat` function of SOFA (src/dat.c). That function will return a warning and give up if the start date is before 1960. + /// :type iers_only: bool + /// :rtype: float pub fn leap_seconds(&self, iers_only: bool) -> Option { self.leap_seconds_with(iers_only, LatestLeapSeconds::default()) } @@ -309,6 +319,7 @@ impl Epoch { #[cfg(feature = "std")] #[must_use] /// The standard ISO format of this epoch (six digits of subseconds) in the _current_ time scale, refer to for format options. + /// :rtype: str pub fn to_isoformat(&self) -> String { use crate::efmt::consts::ISO8601_STD; use crate::efmt::Formatter; @@ -318,6 +329,8 @@ impl Epoch { #[must_use] /// Returns this epoch with respect to the provided time scale. /// This is needed to correctly perform duration conversions in dynamical time scales (e.g. TDB). + /// :type ts: TimeScale + /// :rtype: Duration pub fn to_duration_in_time_scale(&self, ts: TimeScale) -> Duration { self.to_time_scale(ts).duration } @@ -326,6 +339,9 @@ impl Epoch { /// This will return an overflow error if more than one century has past since the reference epoch in the provided time scale. /// If this is _not_ an issue, you should use `epoch.to_duration_in_time_scale().to_parts()` to retrieve both the centuries and the nanoseconds /// in that century. + /// + /// :type time_scale: TimeScale + /// :rtype: int #[allow(clippy::wrong_self_convention)] fn to_nanoseconds_in_time_scale(&self, time_scale: TimeScale) -> Result { let (centuries, nanoseconds) = self.to_duration_in_time_scale(time_scale).to_parts(); @@ -340,54 +356,65 @@ impl Epoch { #[must_use] /// Returns the number of TAI seconds since J1900 + /// :rtype: float pub fn to_tai_seconds(&self) -> f64 { self.to_tai_duration().to_seconds() } #[must_use] /// Returns this time in a Duration past J1900 counted in TAI + /// :rtype: Duration pub fn to_tai_duration(&self) -> Duration { self.to_time_scale(TimeScale::TAI).duration } #[must_use] /// Returns the epoch as a floating point value in the provided unit + /// :type unit: Unit + /// :rtype: float pub fn to_tai(&self, unit: Unit) -> f64 { self.to_tai_duration().to_unit(unit) } #[must_use] /// Returns the TAI parts of this duration + /// :rtype: typing.Tuple pub fn to_tai_parts(&self) -> (i16, u64) { self.to_tai_duration().to_parts() } #[must_use] /// Returns the number of days since J1900 in TAI + /// :rtype: float pub fn to_tai_days(&self) -> f64 { self.to_tai(Unit::Day) } #[must_use] /// Returns the number of UTC seconds since the TAI epoch + /// :rtype: float pub fn to_utc_seconds(&self) -> f64 { self.to_utc(Unit::Second) } #[must_use] /// Returns this time in a Duration past J1900 counted in UTC + /// :rtype: Duration pub fn to_utc_duration(&self) -> Duration { self.to_time_scale(TimeScale::UTC).duration } #[must_use] /// Returns the number of UTC seconds since the TAI epoch + /// :type unit: Unit + /// :rtype: float pub fn to_utc(&self, unit: Unit) -> f64 { self.to_utc_duration().to_unit(unit) } #[must_use] /// Returns the number of UTC days since the TAI epoch + /// :rtype: float pub fn to_utc_days(&self) -> f64 { self.to_utc(Unit::Day) } @@ -395,36 +422,44 @@ impl Epoch { #[must_use] /// `as_mjd_days` creates an Epoch from the provided Modified Julian Date in days as explained /// [here](http://tycho.usno.navy.mil/mjd.html). MJD epoch is Modified Julian Day at 17 November 1858 at midnight. + /// :rtype: float pub fn to_mjd_tai_days(&self) -> f64 { self.to_mjd_tai(Unit::Day) } #[must_use] /// Returns the Modified Julian Date in seconds TAI. + /// :rtype: float pub fn to_mjd_tai_seconds(&self) -> f64 { self.to_mjd_tai(Unit::Second) } #[must_use] /// Returns this epoch as a duration in the requested units in MJD TAI + /// :type unit: Unit + /// :rtype: float pub fn to_mjd_tai(&self, unit: Unit) -> f64 { (self.to_tai_duration() + Unit::Day * MJD_J1900).to_unit(unit) } #[must_use] /// Returns the Modified Julian Date in days UTC. + /// :rtype: float pub fn to_mjd_utc_days(&self) -> f64 { self.to_mjd_utc(Unit::Day) } #[must_use] /// Returns the Modified Julian Date in the provided unit in UTC. + /// :type unit: Unit + /// :rtype: float pub fn to_mjd_utc(&self, unit: Unit) -> f64 { (self.to_utc_duration() + Unit::Day * MJD_J1900).to_unit(unit) } #[must_use] /// Returns the Modified Julian Date in seconds UTC. + /// :rtype: float pub fn to_mjd_utc_seconds(&self) -> f64 { self.to_mjd_utc(Unit::Second) } @@ -433,154 +468,181 @@ impl Epoch { /// Returns the Julian days from epoch 01 Jan -4713, 12:00 (noon) /// as explained in "Fundamentals of astrodynamics and applications", Vallado et al. /// 4th edition, page 182, and on [Wikipedia](https://en.wikipedia.org/wiki/Julian_day). + /// :rtype: float pub fn to_jde_tai_days(&self) -> f64 { self.to_jde_tai(Unit::Day) } #[must_use] /// Returns the Julian Days from epoch 01 Jan -4713 12:00 (noon) in desired Duration::Unit + /// :type unit: Unit + /// :rtype: float pub fn to_jde_tai(&self, unit: Unit) -> f64 { self.to_jde_tai_duration().to_unit(unit) } #[must_use] /// Returns the Julian Days from epoch 01 Jan -4713 12:00 (noon) as a Duration + /// :rtype: Duration pub fn to_jde_tai_duration(&self) -> Duration { self.to_tai_duration() + Unit::Day * MJD_J1900 + Unit::Day * MJD_OFFSET } #[must_use] /// Returns the Julian seconds in TAI. + /// :rtype: float pub fn to_jde_tai_seconds(&self) -> f64 { self.to_jde_tai(Unit::Second) } #[must_use] /// Returns the Julian days in UTC. + /// :rtype: float pub fn to_jde_utc_days(&self) -> f64 { self.to_jde_utc_duration().to_unit(Unit::Day) } #[must_use] /// Returns the Julian days in UTC as a `Duration` + /// :rtype: Duration pub fn to_jde_utc_duration(&self) -> Duration { self.to_utc_duration() + Unit::Day * (MJD_J1900 + MJD_OFFSET) } #[must_use] /// Returns the Julian Days in UTC seconds. + /// :rtype: float pub fn to_jde_utc_seconds(&self) -> f64 { self.to_jde_utc_duration().to_seconds() } #[must_use] /// Returns seconds past TAI epoch in Terrestrial Time (TT) (previously called Terrestrial Dynamical Time (TDT)) + /// :rtype: float pub fn to_tt_seconds(&self) -> f64 { self.to_tt_duration().to_seconds() } #[must_use] /// Returns `Duration` past TAI epoch in Terrestrial Time (TT). + /// :rtype: Duration pub fn to_tt_duration(&self) -> Duration { self.to_time_scale(TimeScale::TT).duration } #[must_use] /// Returns days past TAI epoch in Terrestrial Time (TT) (previously called Terrestrial Dynamical Time (TDT)) + /// :rtype: float pub fn to_tt_days(&self) -> f64 { self.to_tt_duration().to_unit(Unit::Day) } #[must_use] /// Returns the centuries passed J2000 TT + /// :rtype: float pub fn to_tt_centuries_j2k(&self) -> f64 { (self.to_tt_duration() - Unit::Second * ET_EPOCH_S).to_unit(Unit::Century) } #[must_use] /// Returns the duration past J2000 TT + /// :rtype: Duration pub fn to_tt_since_j2k(&self) -> Duration { self.to_tt_duration() - Unit::Second * ET_EPOCH_S } #[must_use] /// Returns days past Julian epoch in Terrestrial Time (TT) (previously called Terrestrial Dynamical Time (TDT)) + /// :rtype: float pub fn to_jde_tt_days(&self) -> f64 { self.to_jde_tt_duration().to_unit(Unit::Day) } #[must_use] + /// :rtype: Duration pub fn to_jde_tt_duration(&self) -> Duration { self.to_tt_duration() + Unit::Day * (MJD_J1900 + MJD_OFFSET) } #[must_use] /// Returns days past Modified Julian epoch in Terrestrial Time (TT) (previously called Terrestrial Dynamical Time (TDT)) + /// :rtype: float pub fn to_mjd_tt_days(&self) -> f64 { self.to_mjd_tt_duration().to_unit(Unit::Day) } #[must_use] + /// :rtype: Duration pub fn to_mjd_tt_duration(&self) -> Duration { self.to_tt_duration() + Unit::Day * MJD_J1900 } #[must_use] /// Returns seconds past GPS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ). + /// :rtype: float pub fn to_gpst_seconds(&self) -> f64 { self.to_gpst_duration().to_seconds() } #[must_use] /// Returns `Duration` past GPS time Epoch. + /// :rtype: Duration pub fn to_gpst_duration(&self) -> Duration { self.to_time_scale(TimeScale::GPST).duration } /// Returns nanoseconds past GPS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ). /// NOTE: This function will return an error if the centuries past GPST time are not zero. + /// :rtype: int pub fn to_gpst_nanoseconds(&self) -> Result { self.to_nanoseconds_in_time_scale(TimeScale::GPST) } #[must_use] /// Returns days past GPS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ). + /// :rtype: float pub fn to_gpst_days(&self) -> f64 { self.to_gpst_duration().to_unit(Unit::Day) } #[must_use] /// Returns seconds past QZSS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ). + /// :rtype: float pub fn to_qzsst_seconds(&self) -> f64 { self.to_qzsst_duration().to_seconds() } #[must_use] /// Returns `Duration` past QZSS time Epoch. + /// :rtype: Duration pub fn to_qzsst_duration(&self) -> Duration { self.to_time_scale(TimeScale::QZSST).duration } /// Returns nanoseconds past QZSS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ). /// NOTE: This function will return an error if the centuries past QZSST time are not zero. + /// :rtype: int pub fn to_qzsst_nanoseconds(&self) -> Result { self.to_nanoseconds_in_time_scale(TimeScale::QZSST) } #[must_use] /// Returns days past QZSS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. ). + /// :rtype: float pub fn to_qzsst_days(&self) -> f64 { self.to_gpst_duration().to_unit(Unit::Day) } #[must_use] /// Returns seconds past GST (Galileo) Time Epoch + /// :rtype: float pub fn to_gst_seconds(&self) -> f64 { self.to_gst_duration().to_seconds() } #[must_use] /// Returns `Duration` past GST (Galileo) time Epoch. + /// :rtype: Duration pub fn to_gst_duration(&self) -> Duration { self.to_time_scale(TimeScale::GST).duration } @@ -588,6 +650,7 @@ impl Epoch { /// Returns nanoseconds past GST (Galileo) Time Epoch, starting on August 21st 1999 Midnight UT /// (cf. ). /// NOTE: This function will return an error if the centuries past GST time are not zero. + /// :rtype: int pub fn to_gst_nanoseconds(&self) -> Result { self.to_nanoseconds_in_time_scale(TimeScale::GST) } @@ -596,18 +659,21 @@ impl Epoch { /// Returns days past GST (Galileo) Time Epoch, /// starting on August 21st 1999 Midnight UT /// (cf. ). + /// :rtype: float pub fn to_gst_days(&self) -> f64 { self.to_gst_duration().to_unit(Unit::Day) } #[must_use] /// Returns seconds past BDT (BeiDou) Time Epoch + /// :rtype: float pub fn to_bdt_seconds(&self) -> f64 { self.to_bdt_duration().to_seconds() } #[must_use] /// Returns `Duration` past BDT (BeiDou) time Epoch. + /// :rtype: Duration pub fn to_bdt_duration(&self) -> Duration { self.to_tai_duration() - BDT_REF_EPOCH.to_tai_duration() } @@ -615,6 +681,7 @@ impl Epoch { #[must_use] /// Returns days past BDT (BeiDou) Time Epoch, defined as Jan 01 2006 UTC /// (cf. ). + /// :rtype: float pub fn to_bdt_days(&self) -> f64 { self.to_bdt_duration().to_unit(Unit::Day) } @@ -622,6 +689,7 @@ impl Epoch { /// Returns nanoseconds past BDT (BeiDou) Time Epoch, defined as Jan 01 2006 UTC /// (cf. ). /// NOTE: This function will return an error if the centuries past GST time are not zero. + /// :rtype: int pub fn to_bdt_nanoseconds(&self) -> Result { self.to_nanoseconds_in_time_scale(TimeScale::BDT) } @@ -629,36 +697,43 @@ impl Epoch { #[allow(clippy::wrong_self_convention)] #[must_use] /// Returns the Duration since the UNIX epoch UTC midnight 01 Jan 1970. + /// :rtype: Duration fn to_unix_duration(&self) -> Duration { self.to_duration_in_time_scale(TimeScale::UTC) - UNIX_REF_EPOCH.to_utc_duration() } #[must_use] /// Returns the duration since the UNIX epoch in the provided unit. + /// :type unit: Unit + /// :rtype: float pub fn to_unix(&self, unit: Unit) -> f64 { self.to_unix_duration().to_unit(unit) } #[must_use] /// Returns the number seconds since the UNIX epoch defined 01 Jan 1970 midnight UTC. + /// :rtype: float pub fn to_unix_seconds(&self) -> f64 { self.to_unix(Unit::Second) } #[must_use] /// Returns the number milliseconds since the UNIX epoch defined 01 Jan 1970 midnight UTC. + /// :rtype: float pub fn to_unix_milliseconds(&self) -> f64 { self.to_unix(Unit::Millisecond) } #[must_use] /// Returns the number days since the UNIX epoch defined 01 Jan 1970 midnight UTC. + /// :rtype: float pub fn to_unix_days(&self) -> f64 { self.to_unix(Unit::Day) } #[must_use] /// Returns the Ephemeris Time seconds past 2000 JAN 01 midnight, matches NASA/NAIF SPICE. + /// :rtype: float pub fn to_et_seconds(&self) -> f64 { self.to_et_duration().to_seconds() } @@ -672,6 +747,7 @@ impl Epoch { /// line with IERS and the documentation in the leap seconds list. /// /// In order to match SPICE, the as_et_duration() function will manually get rid of that difference. + /// :rtype: Duration pub fn to_et_duration(&self) -> Duration { self.to_time_scale(TimeScale::ET).duration } @@ -691,23 +767,28 @@ impl Epoch { /// 6. Set the new candidate as the TDB seconds since J2000 and loop until step 5 breaks the loop, or we've done five iterations. /// 7. At this stage, we have a good approximation of the TDB seconds since J2000. /// 8. Reverse the algorithm given that approximation: compute the `g` offset, compute the difference between TDB and TAI, add the TT offset (32.184 s), and offset by the difference between J1900 and J2000. + /// + /// :rtype: Duration pub fn to_tdb_duration(&self) -> Duration { self.to_time_scale(TimeScale::TDB).duration } #[must_use] /// Returns the Dynamic Barycentric Time (TDB) (higher fidelity SPICE ephemeris time) whose epoch is 2000 JAN 01 noon TAI (cf. ) + /// :rtype: float pub fn to_tdb_seconds(&self) -> f64 { self.to_tdb_duration().to_seconds() } #[must_use] /// Returns the Ephemeris Time JDE past epoch + /// :rtype: float pub fn to_jde_et_days(&self) -> f64 { self.to_jde_et_duration().to_unit(Unit::Day) } #[must_use] + /// :rtype: Duration pub fn to_jde_et_duration(&self) -> Duration { self.to_et_duration() + Unit::Day * (MJD_J1900 + MJD_OFFSET) @@ -715,10 +796,13 @@ impl Epoch { } #[must_use] + /// :type unit: Unit + /// :rtype: float pub fn to_jde_et(&self, unit: Unit) -> f64 { self.to_jde_et_duration().to_unit(unit) } + /// :rtype: Duration #[must_use] pub fn to_jde_tdb_duration(&self) -> Duration { self.to_tdb_duration() @@ -728,36 +812,42 @@ impl Epoch { #[must_use] /// Returns the Dynamic Barycentric Time (TDB) (higher fidelity SPICE ephemeris time) whose epoch is 2000 JAN 01 noon TAI (cf. ) + /// :rtype: float pub fn to_jde_tdb_days(&self) -> f64 { self.to_jde_tdb_duration().to_unit(Unit::Day) } #[must_use] /// Returns the number of days since Dynamic Barycentric Time (TDB) J2000 (used for Archinal et al. rotations) + /// :rtype: float pub fn to_tdb_days_since_j2000(&self) -> f64 { self.to_tdb_duration().to_unit(Unit::Day) } #[must_use] /// Returns the number of centuries since Dynamic Barycentric Time (TDB) J2000 (used for Archinal et al. rotations) + /// :rtype: float pub fn to_tdb_centuries_since_j2000(&self) -> f64 { self.to_tdb_duration().to_unit(Unit::Century) } #[must_use] /// Returns the number of days since Ephemeris Time (ET) J2000 (used for Archinal et al. rotations) + /// :rtype: float pub fn to_et_days_since_j2000(&self) -> f64 { self.to_et_duration().to_unit(Unit::Day) } #[must_use] /// Returns the number of centuries since Ephemeris Time (ET) J2000 (used for Archinal et al. rotations) + /// :rtype: float pub fn to_et_centuries_since_j2000(&self) -> f64 { self.to_et_duration().to_unit(Unit::Century) } #[must_use] /// Returns the duration since the start of the year + /// :rtype: Duration pub fn duration_in_year(&self) -> Duration { let start_of_year = Self::from_gregorian(self.year(), 1, 1, 0, 0, 0, 0, self.time_scale); self.duration - start_of_year.duration @@ -765,52 +855,62 @@ impl Epoch { #[must_use] /// Returns the number of days since the start of the year. + /// :rtype: float pub fn day_of_year(&self) -> f64 { self.duration_in_year().to_unit(Unit::Day) + 1.0 } #[must_use] /// Returns the number of Gregorian years of this epoch in the current time scale. + /// :rtype: int pub fn year(&self) -> i32 { Self::compute_gregorian(self.duration, self.time_scale).0 } #[must_use] /// Returns the year and the days in the year so far (days of year). + /// :rtype: typing.Tuple pub fn year_days_of_year(&self) -> (i32, f64) { (self.year(), self.day_of_year()) } /// Returns the hours of the Gregorian representation of this epoch in the time scale it was initialized in. + /// :rtype: int pub fn hours(&self) -> u64 { self.duration.decompose().2 } /// Returns the minutes of the Gregorian representation of this epoch in the time scale it was initialized in. + /// :rtype: int pub fn minutes(&self) -> u64 { self.duration.decompose().3 } /// Returns the seconds of the Gregorian representation of this epoch in the time scale it was initialized in. + /// :rtype: int pub fn seconds(&self) -> u64 { self.duration.decompose().4 } /// Returns the milliseconds of the Gregorian representation of this epoch in the time scale it was initialized in. + /// :rtype: int pub fn milliseconds(&self) -> u64 { self.duration.decompose().5 } /// Returns the microseconds of the Gregorian representation of this epoch in the time scale it was initialized in. + /// :rtype: int pub fn microseconds(&self) -> u64 { self.duration.decompose().6 } /// Returns the nanoseconds of the Gregorian representation of this epoch in the time scale it was initialized in. + /// :rtype: int pub fn nanoseconds(&self) -> u64 { self.duration.decompose().7 } + /// :rtype: MonthName pub fn month_name(&self) -> MonthName { let month = Self::compute_gregorian(self.duration, self.time_scale).1; month.into() @@ -818,6 +918,7 @@ impl Epoch { #[cfg(feature = "std")] /// Returns this epoch in UTC in the RFC3339 format + /// :rtype: str pub fn to_rfc3339(&self) -> String { let ts = TimeScale::UTC; let (y, mm, dd, hh, min, s, nanos) = diff --git a/src/epoch/ops.rs b/src/epoch/ops.rs index 7cc0e49..30f21d2 100644 --- a/src/epoch/ops.rs +++ b/src/epoch/ops.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use core::cmp::{Ord, Ordering, PartialEq, PartialOrd}; use core::hash::{Hash, Hasher}; diff --git a/src/epoch/python.rs b/src/epoch/python.rs index d55f2c0..1b48d1f 100644 --- a/src/epoch/python.rs +++ b/src/epoch/python.rs @@ -1,9 +1,9 @@ /* -* Hifitime, part of the Nyx Space tools -* Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) -* This Source Code Form is subject to the terms of the Apache -* v. 2.0. If a copy of the Apache License was not distributed with this -* file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. * * Documentation: https://nyxspace.com/ */ @@ -23,84 +23,113 @@ use pyo3::types::PyType; impl Epoch { #[classmethod] /// Creates a new Epoch from a Duration as the time difference between this epoch and TAI reference epoch. + /// :type duration: Duration + /// :rtype: Epoch const fn init_from_tai_duration(_cls: &Bound<'_, PyType>, duration: Duration) -> Self { Self::from_tai_duration(duration) } #[classmethod] /// Creates a new Epoch from its centuries and nanosecond since the TAI reference epoch. + /// :type centuries: int + /// :type nanoseconds: int + /// :rtype: Epoch fn init_from_tai_parts(_cls: &Bound<'_, PyType>, centuries: i16, nanoseconds: u64) -> Self { Self::from_tai_parts(centuries, nanoseconds) } #[classmethod] /// Initialize an Epoch from the provided TAI seconds since 1900 January 01 at midnight + /// :type seconds: float + /// :rtype: Epoch fn init_from_tai_seconds(_cls: &Bound<'_, PyType>, seconds: f64) -> Self { Self::from_tai_seconds(seconds) } #[classmethod] /// Initialize an Epoch from the provided TAI days since 1900 January 01 at midnight + /// :type days: float + /// :rtype: Epoch fn init_from_tai_days(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_tai_days(days) } #[classmethod] /// Initialize an Epoch from the provided UTC seconds since 1900 January 01 at midnight + /// :type seconds: float + /// :rtype: Epoch fn init_from_utc_seconds(_cls: &Bound<'_, PyType>, seconds: f64) -> Self { Self::from_utc_seconds(seconds) } #[classmethod] /// Initialize an Epoch from the provided UTC days since 1900 January 01 at midnight + /// :type days: float + /// :rtype: Epoch fn init_from_utc_days(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_utc_days(days) } #[classmethod] /// Initialize an Epoch from given MJD in TAI time scale + /// :type days: float + /// :rtype: Epoch fn init_from_mjd_tai(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_mjd_tai(days) } #[classmethod] /// Initialize an Epoch from given MJD in UTC time scale + /// :type days: float + /// :rtype: Epoch fn init_from_mjd_utc(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_mjd_utc(days) } #[classmethod] /// Initialize an Epoch from given JDE in TAI time scale + /// :type days: float + /// :rtype: Epoch fn init_from_jde_tai(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_jde_tai(days) } #[classmethod] /// Initialize an Epoch from given JDE in UTC time scale + /// :type days: float + /// :rtype: Epoch fn init_from_jde_utc(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_jde_utc(days) } #[classmethod] /// Initialize an Epoch from the provided TT seconds (approximated to 32.184s delta from TAI) + /// :type seconds: float + /// :rtype: Epoch fn init_from_tt_seconds(_cls: &Bound<'_, PyType>, seconds: f64) -> Self { Self::from_tt_seconds(seconds) } #[classmethod] /// Initialize an Epoch from the provided TT seconds (approximated to 32.184s delta from TAI) + /// :type duration: Duration + /// :rtype: Epoch fn init_from_tt_duration(_cls: &Bound<'_, PyType>, duration: Duration) -> Self { Self::from_tt_duration(duration) } #[classmethod] /// Initialize an Epoch from the Ephemeris Time seconds past 2000 JAN 01 (J2000 reference) + /// :type seconds_since_j2000: float + /// :rtype: Epoch fn init_from_et_seconds(_cls: &Bound<'_, PyType>, seconds_since_j2000: f64) -> Epoch { Self::from_et_seconds(seconds_since_j2000) } #[classmethod] /// Initialize an Epoch from the Ephemeris Time duration past 2000 JAN 01 (J2000 reference) + /// :type duration_since_j2000: Duration + /// :rtype: Epoch fn init_from_et_duration(_cls: &Bound<'_, PyType>, duration_since_j2000: Duration) -> Self { Self::from_et_duration(duration_since_j2000) } @@ -109,24 +138,32 @@ impl Epoch { /// Initialize an Epoch from Dynamic Barycentric Time (TDB) seconds past 2000 JAN 01 midnight (difference than SPICE) /// NOTE: This uses the ESA algorithm, which is a notch more complicated than the SPICE algorithm, but more precise. /// In fact, SPICE algorithm is precise +/- 30 microseconds for a century whereas ESA algorithm should be exactly correct. + /// :type seconds_j2000: float + /// :rtype: Epoch fn init_from_tdb_seconds(_cls: &Bound<'_, PyType>, seconds_j2000: f64) -> Epoch { Self::from_tdb_seconds(seconds_j2000) } #[classmethod] /// Initialize from Dynamic Barycentric Time (TDB) (same as SPICE ephemeris time) whose epoch is 2000 JAN 01 noon TAI. + /// :type duration_since_j2000: Duration + /// :rtype: Epoch fn init_from_tdb_duration(_cls: &Bound<'_, PyType>, duration_since_j2000: Duration) -> Epoch { Self::from_tdb_duration(duration_since_j2000) } #[classmethod] /// Initialize from the JDE days + /// :type days: float + /// :rtype: Epoch fn init_from_jde_et(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_jde_et(days) } #[classmethod] /// Initialize from Dynamic Barycentric Time (TDB) (same as SPICE ephemeris time) in JD days + /// :type days: float + /// :rtype: Epoch fn init_from_jde_tdb(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_jde_tdb(days) } @@ -134,6 +171,8 @@ impl Epoch { #[classmethod] /// Initialize an Epoch from the number of seconds since the GPS Time Epoch, /// defined as UTC midnight of January 5th to 6th 1980 (cf. ). + /// :type seconds: float + /// :rtype: Epoch fn init_from_gpst_seconds(_cls: &Bound<'_, PyType>, seconds: f64) -> Self { Self::from_gpst_seconds(seconds) } @@ -141,6 +180,8 @@ impl Epoch { #[classmethod] /// Initialize an Epoch from the number of days since the GPS Time Epoch, /// defined as UTC midnight of January 5th to 6th 1980 (cf. ). + /// :type days: float + /// :rtype: Epoch fn init_from_gpst_days(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_gpst_days(days) } @@ -149,6 +190,8 @@ impl Epoch { /// Initialize an Epoch from the number of nanoseconds since the GPS Time Epoch, /// defined as UTC midnight of January 5th to 6th 1980 (cf. ). /// This may be useful for time keeping devices that use GPS as a time source. + /// :type nanoseconds: float + /// :rtype: Epoch fn init_from_gpst_nanoseconds(_cls: &Bound<'_, PyType>, nanoseconds: u64) -> Self { Self::from_gpst_nanoseconds(nanoseconds) } @@ -156,6 +199,8 @@ impl Epoch { #[classmethod] /// Initialize an Epoch from the number of seconds since the QZSS Time Epoch, /// defined as UTC midnight of January 5th to 6th 1980 (cf. ). + /// :type seconds: float + /// :rtype: Epoch fn init_from_qzsst_seconds(_cls: &Bound<'_, PyType>, seconds: f64) -> Self { Self::from_qzsst_seconds(seconds) } @@ -163,6 +208,8 @@ impl Epoch { #[classmethod] /// Initialize an Epoch from the number of days since the QZSS Time Epoch, /// defined as UTC midnight of January 5th to 6th 1980 (cf. ). + /// :type days: float + /// :rtype: Epoch fn init_from_qzsst_days(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_qzsst_days(days) } @@ -171,6 +218,8 @@ impl Epoch { /// Initialize an Epoch from the number of nanoseconds since the QZSS Time Epoch, /// defined as UTC midnight of January 5th to 6th 1980 (cf. ). /// This may be useful for time keeping devices that use QZSS as a time source. + /// :type nanoseconds: int + /// :rtype: Epoch fn init_from_qzsst_nanoseconds(_cls: &Bound<'_, PyType>, nanoseconds: u64) -> Self { Self::from_qzsst_nanoseconds(nanoseconds) } @@ -179,6 +228,8 @@ impl Epoch { /// Initialize an Epoch from the number of seconds since the Galileo Time Epoch, /// starting on August 21st 1999 Midnight UT, /// (cf. ). + /// :type seconds: float + /// :rtype: Epoch fn init_from_gst_seconds(_cls: &Bound<'_, PyType>, seconds: f64) -> Self { Self::from_gst_seconds(seconds) } @@ -187,6 +238,8 @@ impl Epoch { /// Initialize an Epoch from the number of days since the Galileo Time Epoch, /// starting on August 21st 1999 Midnight UT, /// (cf. ). + /// :type days: float + /// :rtype: Epoch fn init_from_gst_days(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_gst_days(days) } @@ -196,6 +249,8 @@ impl Epoch { /// starting on August 21st 1999 Midnight UT, /// (cf. ). /// This may be useful for time keeping devices that use GST as a time source. + /// :type nanoseconds: float + /// :rtype: Epoch fn init_from_gst_nanoseconds(_cls: &Bound<'_, PyType>, nanoseconds: u64) -> Self { Self::from_gst_nanoseconds(nanoseconds) } @@ -203,6 +258,8 @@ impl Epoch { #[classmethod] /// Initialize an Epoch from the number of seconds since the BeiDou Time Epoch, /// defined as January 1st 2006 (cf. ). + /// :type seconds: float + /// :rtype: Epoch fn init_from_bdt_seconds(_cls: &Bound<'_, PyType>, seconds: f64) -> Self { Self::from_bdt_seconds(seconds) } @@ -210,6 +267,8 @@ impl Epoch { #[classmethod] /// Initialize an Epoch from the number of days since the BeiDou Time Epoch, /// defined as January 1st 2006 (cf. ). + /// :type days: float + /// :rtype: Epoch fn init_from_bdt_days(_cls: &Bound<'_, PyType>, days: f64) -> Self { Self::from_bdt_days(days) } @@ -218,23 +277,39 @@ impl Epoch { /// Initialize an Epoch from the number of days since the BeiDou Time Epoch, /// defined as January 1st 2006 (cf. ). /// This may be useful for time keeping devices that use BDT as a time source. + /// :type nanoseconds: float + /// :rtype: Epoch fn init_from_bdt_nanoseconds(_cls: &Bound<'_, PyType>, nanoseconds: u64) -> Self { Self::from_bdt_nanoseconds(nanoseconds) } #[classmethod] /// Initialize an Epoch from the provided UNIX second timestamp since UTC midnight 1970 January 01. + /// :type seconds: float + /// :rtype: Epoch fn init_from_unix_seconds(_cls: &Bound<'_, PyType>, seconds: f64) -> Self { Self::from_unix_seconds(seconds) } #[classmethod] /// Initialize an Epoch from the provided UNIX millisecond timestamp since UTC midnight 1970 January 01. + /// :type milliseconds: float + /// :rtype: Epoch fn init_from_unix_milliseconds(_cls: &Bound<'_, PyType>, milliseconds: f64) -> Self { Self::from_unix_milliseconds(milliseconds) } #[classmethod] + /// Initialize from the Gregorian parts + /// :type year: int + /// :type month: int + /// :type day: int + /// :type hour: int + /// :type minute: int + /// :type second: int + /// :type nanos: int + /// :type time_scale: TimeScale + /// :rtype: Epoch fn init_from_gregorian( _cls: &Bound<'_, PyType>, year: i32, @@ -245,21 +320,33 @@ impl Epoch { second: u8, nanos: u32, time_scale: TimeScale, - ) -> Self { - Self::from_gregorian(year, month, day, hour, minute, second, nanos, time_scale) + ) -> Result { + Self::maybe_from_gregorian(year, month, day, hour, minute, second, nanos, time_scale) } #[classmethod] + /// Initialize from the Gregorian parts, time set to noon + /// :type year: int + /// :type month: int + /// :type day: int + /// :type time_scale: TimeScale + /// :rtype: Epoch fn init_from_gregorian_at_noon( _cls: &Bound<'_, PyType>, year: i32, month: u8, day: u8, time_scale: TimeScale, - ) -> Self { - Self::from_gregorian_at_noon(year, month, day, time_scale) + ) -> Result { + Self::maybe_from_gregorian(year, month, day, 12, 0, 0, 0, time_scale) } + /// Initialize from the Gregorian parts, time set to midnight + /// :type year: int + /// :type month: int + /// :type day: int + /// :type time_scale: TimeScale + /// :rtype: Epoch #[classmethod] fn init_from_gregorian_at_midnight( _cls: &Bound<'_, PyType>, @@ -267,98 +354,23 @@ impl Epoch { month: u8, day: u8, time_scale: TimeScale, - ) -> Self { - Self::from_gregorian_at_midnight(year, month, day, time_scale) - } - - #[classmethod] - /// Attempts to build an Epoch from the provided Gregorian date and time in TAI. - fn maybe_init_from_gregorian_tai( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - hour: u8, - minute: u8, - second: u8, - nanos: u32, ) -> Result { - Self::maybe_from_gregorian_tai(year, month, day, hour, minute, second, nanos) - } - - #[classmethod] - /// Attempts to build an Epoch from the provided Gregorian date and time in the provided time scale. - /// NOTE: If the time scale is TDB, this function assumes that the SPICE format is used - #[allow(clippy::too_many_arguments)] - fn maybe_init_from_gregorian( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - hour: u8, - minute: u8, - second: u8, - nanos: u32, - time_scale: TimeScale, - ) -> Result { - Self::maybe_from_gregorian(year, month, day, hour, minute, second, nanos, time_scale) + Self::maybe_from_gregorian(year, month, day, 0, 0, 0, 0, time_scale) } #[classmethod] /// Builds an Epoch from the provided Gregorian date and time in TAI. If invalid date is provided, this function will panic. /// Use maybe_from_gregorian_tai if unsure. - fn init_from_gregorian_tai( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - hour: u8, - minute: u8, - second: u8, - nanos: u32, - ) -> Self { - Self::from_gregorian_tai(year, month, day, hour, minute, second, nanos) - } - - #[classmethod] - /// Initialize from the Gregorian date at midnight in TAI. - fn init_from_gregorian_tai_at_midnight( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - ) -> Self { - Self::from_gregorian_tai_at_midnight(year, month, day) - } - - #[classmethod] - /// Initialize from the Gregorian date at noon in TAI - fn init_from_gregorian_tai_at_noon( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - ) -> Self { - Self::from_gregorian_tai_at_noon(year, month, day) - } - - #[classmethod] - /// Initialize from the Gregorian date and time (without the nanoseconds) in TAI - fn init_from_gregorian_tai_hms( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - hour: u8, - minute: u8, - second: u8, - ) -> Self { - Self::from_gregorian_tai_hms(year, month, day, hour, minute, second) - } - - #[classmethod] - /// Attempts to build an Epoch from the provided Gregorian date and time in UTC. - fn maybe_init_from_gregorian_utc( + /// + /// :type year: int + /// :type month: int + /// :type day: int + /// :type hour: int + /// :type minute: int + /// :type second: int + /// :type nanos: int + /// :rtype: Epoch + fn init_from_gregorian_utc( _cls: &Bound<'_, PyType>, year: i32, month: u8, @@ -371,65 +383,18 @@ impl Epoch { Self::maybe_from_gregorian_utc(year, month, day, hour, minute, second, nanos) } - #[classmethod] - /// Builds an Epoch from the provided Gregorian date and time in TAI. If invalid date is provided, this function will panic. - /// Use maybe_from_gregorian_tai if unsure. - fn init_from_gregorian_utc( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - hour: u8, - minute: u8, - second: u8, - nanos: u32, - ) -> Self { - Self::from_gregorian_utc(year, month, day, hour, minute, second, nanos) - } - - #[classmethod] - /// Initialize from Gregorian date in UTC at midnight - fn init_from_gregorian_utc_at_midnight( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - ) -> Self { - Self::from_gregorian_utc_at_midnight(year, month, day) - } - - #[classmethod] - /// Initialize from Gregorian date in UTC at noon - fn init_from_gregorian_utc_at_noon( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - ) -> Self { - Self::from_gregorian_utc_at_noon(year, month, day) - } - - #[classmethod] - /// Initialize from the Gregorian date and time (without the nanoseconds) in UTC - fn init_from_gregorian_utc_hms( - _cls: &Bound<'_, PyType>, - year: i32, - month: u8, - day: u8, - hour: u8, - minute: u8, - second: u8, - ) -> Self { - Self::from_gregorian_utc_hms(year, month, day, hour, minute, second) - } - #[classmethod] /// Equivalent to `datetime.strptime`, refer to for format options + /// :type epoch_str: str + /// :type format_str: str + /// :rtype: Epoch fn strptime(_cls: &Bound<'_, PyType>, epoch_str: String, format_str: String) -> PyResult { Self::from_format_str(&epoch_str, &format_str).map_err(|e| PyErr::from(e)) } /// Equivalent to `datetime.strftime`, refer to for format options + /// :type format_str: str + /// :rtype: str fn strftime(&self, format_str: String) -> PyResult { use crate::efmt::Formatter; let fmt = Format::from_str(&format_str)?; @@ -437,6 +402,7 @@ impl Epoch { } /// Equivalent to `datetime.isoformat`, and truncated to 23 chars, refer to for format options + /// :rtype: str fn isoformat(&self) -> PyResult { Ok(self.to_isoformat()) } @@ -454,6 +420,10 @@ impl Epoch { /// /// # Why does this function return an `Option` when the other returns a value /// This is to match the `iauDat` function of SOFA (src/dat.c). That function will return a warning and give up if the start date is before 1960. + /// + /// :type iers_only: bool + /// :type provider: LeapSecondsFile + /// :rtype: float #[cfg(feature = "python")] pub fn leap_seconds_with_file( &self, @@ -468,6 +438,9 @@ impl Epoch { } #[classmethod] + /// Returns the computer clock in UTC + /// + /// :rtype: Epoch fn system_now(_cls: &Bound<'_, PyType>) -> Result { Self::now() } @@ -488,6 +461,9 @@ impl Epoch { *self - duration } + /// Differences between two epochs + /// :type other: Duration + /// :rtype: Duration fn timedelta(&self, other: Self) -> Duration { *self - other } diff --git a/src/epoch/system_time.rs b/src/epoch/system_time.rs index c78929f..58820fa 100644 --- a/src/epoch/system_time.rs +++ b/src/epoch/system_time.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use crate::{Duration, Epoch, HifitimeError}; diff --git a/src/epoch/ut1.rs b/src/epoch/ut1.rs index 25be8d7..6acfc84 100644 --- a/src/epoch/ut1.rs +++ b/src/epoch/ut1.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ #[cfg(feature = "python")] use pyo3::prelude::*; diff --git a/src/epoch/with_funcs.rs b/src/epoch/with_funcs.rs index 83f7af1..707745e 100644 --- a/src/epoch/with_funcs.rs +++ b/src/epoch/with_funcs.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use crate::{Duration, Epoch}; diff --git a/src/errors.rs b/src/errors.rs index 41934d4..f576fe2 100644 --- a/src/errors.rs +++ b/src/errors.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use core::num::ParseIntError; use snafu::prelude::*; diff --git a/src/kani_verif.rs b/src/kani_verif.rs index dadf52b..12f068c 100644 --- a/src/kani_verif.rs +++ b/src/kani_verif.rs @@ -1,3 +1,13 @@ +/* +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ + use super::{Duration, Epoch, TimeSeries, Weekday}; use crate::parser::Token; diff --git a/src/lib.rs b/src/lib.rs index d175f27..5e5abf8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,14 +2,14 @@ #![cfg_attr(docsrs, feature(doc_cfg))] #![cfg_attr(not(feature = "std"), no_std)] /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ /// Julian date for the J1900 epoch, as per NAIF SPICE. pub const JD_J1900: f64 = 2_415_020.0; diff --git a/src/month.rs b/src/month.rs index 86bfe27..5b97da8 100644 --- a/src/month.rs +++ b/src/month.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use crate::ParsingError; use core::fmt; diff --git a/src/parser.rs b/src/parser.rs index 9d43d1c..2abb145 100644 --- a/src/parser.rs +++ b/src/parser.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use crate::{HifitimeError, ParsingError}; diff --git a/src/python.rs b/src/python.rs index 7787801..13b262c 100644 --- a/src/python.rs +++ b/src/python.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use pyo3::{ exceptions::PyException, @@ -17,6 +17,7 @@ use pyo3::{ use crate::leap_seconds::{LatestLeapSeconds, LeapSecondsFile}; use crate::prelude::*; use crate::ut1::Ut1Provider; +use crate::MonthName; // Keep the module at the top #[pymodule] @@ -29,6 +30,7 @@ fn hifitime(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> { m.add_class::()?; m.add_class::()?; m.add_class::()?; + m.add_class::()?; m.add_class::()?; m.add_class::()?; m.add_class::()?; diff --git a/src/timescale/fmt.rs b/src/timescale/fmt.rs index 6f7a57b..05e677f 100644 --- a/src/timescale/fmt.rs +++ b/src/timescale/fmt.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use core::fmt; use core::str::FromStr; diff --git a/src/timescale/kani.rs b/src/timescale/kani.rs index 565f937..e1b50ce 100644 --- a/src/timescale/kani.rs +++ b/src/timescale/kani.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use super::TimeScale; use kani::Arbitrary; diff --git a/src/timescale/mod.rs b/src/timescale/mod.rs index 96fdfc4..be1d4e6 100644 --- a/src/timescale/mod.rs +++ b/src/timescale/mod.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ #[cfg(feature = "python")] use pyo3::prelude::*; @@ -174,6 +174,7 @@ impl TimeScale { #[cfg_attr(feature = "python", pymethods)] impl TimeScale { /// Returns true if self takes leap seconds into account + /// :rtype: bool pub const fn uses_leap_seconds(&self) -> bool { matches!(self, Self::UTC) } diff --git a/src/timeseries.rs b/src/timeseries.rs index 3009d5f..c12e350 100644 --- a/src/timeseries.rs +++ b/src/timeseries.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use super::{Duration, Epoch}; @@ -26,6 +26,13 @@ NOTE: This is taken from itertools: https://docs.rs/itertools-num/0.1.3/src/iter */ /// An iterator of a sequence of evenly spaced Epochs. +/// +/// (Python documentation hints) +/// :type start: Epoch +/// :type end: Epoch +/// :type step: Duration +/// :type inclusive: bool +/// :rtype: TimeSeries #[cfg_attr(kani, derive(kani::Arbitrary))] #[derive(Clone, Debug, PartialEq, Eq)] #[cfg_attr(feature = "python", pyclass)] diff --git a/src/timeunits.rs b/src/timeunits.rs index 2d728fa..19aa964 100644 --- a/src/timeunits.rs +++ b/src/timeunits.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use core::ops::{Add, Mul, Sub}; diff --git a/src/weekday.rs b/src/weekday.rs index f1e6e56..cfdca4f 100644 --- a/src/weekday.rs +++ b/src/weekday.rs @@ -1,12 +1,12 @@ /* - * Hifitime, part of the Nyx Space tools - * Copyright (C) 2017-onwards Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) - * This Source Code Form is subject to the terms of the Apache - * v. 2.0. If a copy of the Apache License was not distributed with this - * file, You can obtain one at https://www.apache.org/licenses/LICENSE-2.0. - * - * Documentation: https://nyxspace.com/ - */ +* Hifitime +* Copyright (C) 2017-onward Christopher Rabotin et al. (cf. https://github.com/nyx-space/hifitime/graphs/contributors) +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at https://mozilla.org/MPL/2.0/. +* +* Documentation: https://nyxspace.com/ +*/ use crate::{Duration, ParsingError, Unit}; use core::fmt;