| Name | crifx JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | None |
| Summary | icpc-style Contest pReparation Insights tool For anyone (X). |
| upload_time | 2024-11-04 04:08:27 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License Copyright (c) 2024 Finn Lidbetter Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
icpc
contest
competitive programming
problemtools
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CRIFX
CRIFX is the Contest pReparation Insights tool For anyone (X).
Its purpose is to automatically produce pdf reports that give insights into
tasks that are completed and tasks that are still outstanding in preparing
an icpc-style competitive programming contest.
## Installation
Install crifx with `pip install crifx`. Building the report will require some
TeX packages. For example, on Ubuntu 22.04 installing the `texlive-latex-extra`
apt package with `apt-get install texlive-latex-extra` should be sufficient.
If you are using a different operating system, and you are able to run crifx, then
please share your experience by opening an Issue and I would be pleased to update
installation instructions accordingly.
## Using crifx
In the root directory for a problemset, run `crifx` from within a problemset nested
directory, or run `crifx /path/to/problemset/root` from anywhere to generate a report
for the problemset at the specified path.
If there is no `crifx.toml` configuration file in the problemset root directory,
then a report will be created using default configuration values.
Crifx can be configured by adding a `crifx.toml` file to the root of the problemset
directory. The configuration can be used to define requirements on things like
the number of indepenedent AC submissions for each problem, groups of programming
languages and the number of submissions needed from each group or the number of
distinct groups required. The configuration file can also be used to specify the
names of people involved in contest preparation such that filenames and special
strings in judge submissions can be used to associate submissions with those
people.
## Counting independent submissions
### How crifx decides the author of a submission
In order of precedence, crifx determines the author of a file by:
1. The presence of a crifx!(author="name") string in the text of a submission file.
2. The presence of an underscore separated name string that matches an alias in the
`crifx.toml` configuration file.
3. The git user associated with the largest number of lines in the git blame. Roughly speaking this will be
the git user that created/changed the largest number of lines in the current revision.
The `crifx.toml` file is used to define the aliases of a submission author and associate them with
a git username. More details to come, including an example.
If you encounter a scenario where crifx is incorrectly attributing a submission to the wrong person
and it cannot easily be fixed by adding a user and alias to the `crifx.toml` file.
Crifx does not yet support disambiguating git users with the same git name.
## Configuration
### Top-level
The top-level configuration of `crifx` is defined in a TOML text file named
`crifx.toml` placed in the directory containing the directories for each problem.
- `github_repo_url`. Optional. String. Default: `null`. The GitHub repository url for
the problem set. This should be the root url for the repository and not the url to
some directory in the repository tree.
#### `[review_requirements]`
- `independent_ac`. Optional. Integer. Default: `3`.
- `language_groups`. Optional. Integer. Default: `2`.
- `submissions_wa`. Optional. Integer. Default: `1`.
- `submissions_tle`. Optional. Integer. Default: `1`.
- `statement_reviewers`. Optional. Integer. Default: `3`.
- `validator_reviewers`. Optional. Integer. Default: `2`.
- `data_reviewers`. Optional. Integer. Default: `2`.
#### `[[judge]]`
The `judge` array of tables is used to associate judge names and aliases. The
judge name can also optionally be associated with a git name.
- `primary_name`. Required. String. A name to identify the judge with. This name
will be used in the `crifx` report when listing who wrote each submission and who
is ineligible to provide further contributions for a problem.
- `git_name`. Optional. String. This is the git name for the judge if they
have one. Note that this is _not_ the GitHub username. From the command line, you
can see your git name with the command `git config user.name`. By
specifying a `git_name`, submissions from a judge that are uploaded or edited by
someone else can be associated with submissions that the judge themself uploads.
For the submission uploaded by someone else, the submission will need to be
identified by file name or a `crifx!(author=name)` string in the submission file.
- `aliases`. Optional. Array of Strings. List of aliases that can be used to identify
the judge. Submission file names are split into parts by underscores. If any part
matches an alias of a judge, then the submission is assumed to belong to the judge
with the alias and associated primary name/git name. Aliases can also be used in
`crifx!(author=name)` strings inside submission files to identify a judge.
#### `[[language_group]]`
- `name`. Required. String. A name to use for the language group. E.g., `"C/C++"`
- `languages`. Required. Array of Strings. A list of languages to include in the
group. The languages must be known to `crifx`.
- `required_ac_count`. Optional. Integer. Default: `0`. The number of Accepted
submissions that are required for this language group. E.g., a value of `2` means
that each problem must have at least `2` accepted submissions from languages in
this language group.
### Per problem configuration
For each problem, a TOML text file placed in the root directory for the problem
(i.e., at the same level as the `problem.yaml` file and the `submissions` directory),
called `crifx-problem-status.toml`. This file can be used to track who has reviewed
different parts of a problem. It can also be used to define some per-problem configuration.
- `github_issue_id`. Optional. Integer. Default: `null`. The GitHub Issue id number
for a GitHub Issue that may have been created to discuss the problem. This is used
to generate links to the GitHub Issue url from within the `crifx` report.
#### `[review_status]`
- `statement_reviewed_by`. Optional. Array of Strings. A list of judge aliases for
judges that have reviewed the problem statement and are happy with the state of the
problem statement for use in a contest. The judge's name should only be added to this
list if they think that the statement is clear and unambiguous.
- `validators_reviewed_by`. Optional. Array of Strings. A list of judge aliases for
judges that have reviewed the input (and output) validators. The judge's name should
only be added to this list if they have verified that the input validator checks all
guarantees made in the problem statement about the input data.
- `data_reviewed_by`. Optional. Array of Strings. A list of judge aliases for judges
that have reviewed the test data (secret and sample). The judge's name should only
be added to this list if they have inspected the generated test data and after doing
so they cannot think of another test case that should be added to ensure that correct
submissions will be judged as correct and incorrect submissions will be judged as
incorrect.
## Example
Below is an example `crifx.toml` file.
```toml
# Crifx configuration file example.
# The github repository url for this problemset. This can be used to include
# hyperlinks to GitHub Issues for each problem in the report.
github_repo_url = "https://github.com/FinnLidbetter/crifx"
# Section for defining minimum numbers of submissions and manual reviews.
[review_requirements]
# There must be AC submissions from at least 3 distinct judges.
independent_ac = 3
# There must be at least 2 distinct language groups with at least one AC
# submission written in a language in the group.
language_groups = 2
# There must be at least one wrong_answer submission.
submissions_wa = 1
# There must be at least one time_limit_exceeded submission.
submissions_tle = 1
# There must be at least 3 judges who have reviewed the problem statement.
statement_reviewers = 3
# There must be at least 2 judges who have reviewed the input validators.
validator_reviewers = 2
# There must be at least 2 judges who have reviewed the test data.
data_reviewers = 2
# Define judge names in `[[judge]]` tables.
[[judge]]
# Primary name is required.
primary_name = "Jane Doe"
# git_name is not required.
# git_name = "janedoe"
# Aliases is a list of zero or more alternative names.
aliases = ["jd", "jane"]
[[judge]]
primary_name = "Homer Simpson"
git_name = "homers123"
aliases = []
# Tables for defining language groups.
[[language_group]]
# Non alphanumeric characters can be used in the language group name.
name = "c/c++"
# The names of the languages in the group. Language names are cast to
# lowercase before comparison to language names known to crifx.
languages = ["C", "C++"]
# The number of AC submissions required for this group.
required_ac_count = 0
[[language_group]]
name = "java/kotlin"
languages = ["Java", "Kotlin"]
required_ac_count = 0
[[language_group]]
name = "python"
languages = ["Python"]
required_ac_count = 0
```
Here is an example `crifx-problem-status.toml` file inside the
`examples/example_problemset/helloworld/` directory.
```toml
# GitHub Issue id number associated with this problem.
github_issue_id = 1
[review_status]
# List of names of judges who have reviewed the problem statement.
statement_reviewed_by = [
"Alice",
"Bob",
"Jane Doe",
]
# List of names of judges who have reviewed the input validator(s).
validators_reviewed_by = [
"Homer Simpson",
]
# List of names of judges who have reviewed the test data.
data_reviewed_by = [
"Homer Simpson",
"Bob",
]
```
This example report screenshot is produced from the example in `examples/example_problemset`
Raw data
{
"_id": null,
"home_page": null,
"name": "crifx",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "icpc, contest, competitive programming, problemtools",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/25/67/285016a73a625e79bc57100417f80998f10a8a3b21456acb9ff8c7fe72e9/crifx-0.1.4.tar.gz",
"platform": null,
"description": "# CRIFX\n\nCRIFX is the Contest pReparation Insights tool For anyone (X).\n\nIts purpose is to automatically produce pdf reports that give insights into\ntasks that are completed and tasks that are still outstanding in preparing\nan icpc-style competitive programming contest.\n\n## Installation\nInstall crifx with `pip install crifx`. Building the report will require some\nTeX packages. For example, on Ubuntu 22.04 installing the `texlive-latex-extra` \napt package with `apt-get install texlive-latex-extra` should be sufficient.\n\nIf you are using a different operating system, and you are able to run crifx, then \nplease share your experience by opening an Issue and I would be pleased to update\ninstallation instructions accordingly.\n\n## Using crifx\nIn the root directory for a problemset, run `crifx` from within a problemset nested\ndirectory, or run `crifx /path/to/problemset/root` from anywhere to generate a report\nfor the problemset at the specified path. \nIf there is no `crifx.toml` configuration file in the problemset root directory, \nthen a report will be created using default configuration values.\n\nCrifx can be configured by adding a `crifx.toml` file to the root of the problemset \ndirectory. The configuration can be used to define requirements on things like\nthe number of indepenedent AC submissions for each problem, groups of programming\nlanguages and the number of submissions needed from each group or the number of \ndistinct groups required. The configuration file can also be used to specify the\nnames of people involved in contest preparation such that filenames and special\nstrings in judge submissions can be used to associate submissions with those \npeople.\n\n## Counting independent submissions\n\n### How crifx decides the author of a submission\nIn order of precedence, crifx determines the author of a file by:\n1. The presence of a crifx!(author=\"name\") string in the text of a submission file.\n2. The presence of an underscore separated name string that matches an alias in the\n `crifx.toml` configuration file.\n3. The git user associated with the largest number of lines in the git blame. Roughly speaking this will be\n the git user that created/changed the largest number of lines in the current revision.\n\nThe `crifx.toml` file is used to define the aliases of a submission author and associate them with\na git username. More details to come, including an example.\n\nIf you encounter a scenario where crifx is incorrectly attributing a submission to the wrong person\nand it cannot easily be fixed by adding a user and alias to the `crifx.toml` file.\nCrifx does not yet support disambiguating git users with the same git name.\n\n## Configuration\n\n### Top-level\nThe top-level configuration of `crifx` is defined in a TOML text file named \n`crifx.toml` placed in the directory containing the directories for each problem.\n\n\n- `github_repo_url`. Optional. String. Default: `null`. The GitHub repository url for \nthe problem set. This should be the root url for the repository and not the url to \nsome directory in the repository tree.\n\n#### `[review_requirements]`\n\n- `independent_ac`. Optional. Integer. Default: `3`.\n- `language_groups`. Optional. Integer. Default: `2`.\n- `submissions_wa`. Optional. Integer. Default: `1`.\n- `submissions_tle`. Optional. Integer. Default: `1`.\n- `statement_reviewers`. Optional. Integer. Default: `3`.\n- `validator_reviewers`. Optional. Integer. Default: `2`.\n- `data_reviewers`. Optional. Integer. Default: `2`.\n\n#### `[[judge]]`\nThe `judge` array of tables is used to associate judge names and aliases. The\njudge name can also optionally be associated with a git name.\n- `primary_name`. Required. String. A name to identify the judge with. This name\nwill be used in the `crifx` report when listing who wrote each submission and who \nis ineligible to provide further contributions for a problem. \n- `git_name`. Optional. String. This is the git name for the judge if they \nhave one. Note that this is _not_ the GitHub username. From the command line, you \ncan see your git name with the command `git config user.name`. By \nspecifying a `git_name`, submissions from a judge that are uploaded or edited by \nsomeone else can be associated with submissions that the judge themself uploads. \nFor the submission uploaded by someone else, the submission will need to be \nidentified by file name or a `crifx!(author=name)` string in the submission file.\n- `aliases`. Optional. Array of Strings. List of aliases that can be used to identify \nthe judge. Submission file names are split into parts by underscores. If any part \nmatches an alias of a judge, then the submission is assumed to belong to the judge \nwith the alias and associated primary name/git name. Aliases can also be used in\n`crifx!(author=name)` strings inside submission files to identify a judge.\n\n#### `[[language_group]]`\n- `name`. Required. String. A name to use for the language group. E.g., `\"C/C++\"`\n- `languages`. Required. Array of Strings. A list of languages to include in the\ngroup. The languages must be known to `crifx`.\n- `required_ac_count`. Optional. Integer. Default: `0`. The number of Accepted \nsubmissions that are required for this language group. E.g., a value of `2` means \nthat each problem must have at least `2` accepted submissions from languages in \nthis language group.\n\n### Per problem configuration\nFor each problem, a TOML text file placed in the root directory for the problem\n(i.e., at the same level as the `problem.yaml` file and the `submissions` directory), \ncalled `crifx-problem-status.toml`. This file can be used to track who has reviewed\ndifferent parts of a problem. It can also be used to define some per-problem configuration.\n\n- `github_issue_id`. Optional. Integer. Default: `null`. The GitHub Issue id number \nfor a GitHub Issue that may have been created to discuss the problem. This is used \nto generate links to the GitHub Issue url from within the `crifx` report.\n\n#### `[review_status]`\n- `statement_reviewed_by`. Optional. Array of Strings. A list of judge aliases for \njudges that have reviewed the problem statement and are happy with the state of the\nproblem statement for use in a contest. The judge's name should only be added to this \nlist if they think that the statement is clear and unambiguous.\n- `validators_reviewed_by`. Optional. Array of Strings. A list of judge aliases for\njudges that have reviewed the input (and output) validators. The judge's name should \nonly be added to this list if they have verified that the input validator checks all \nguarantees made in the problem statement about the input data.\n- `data_reviewed_by`. Optional. Array of Strings. A list of judge aliases for judges \nthat have reviewed the test data (secret and sample). The judge's name should only \nbe added to this list if they have inspected the generated test data and after doing \nso they cannot think of another test case that should be added to ensure that correct \nsubmissions will be judged as correct and incorrect submissions will be judged as \nincorrect.\n\n## Example\nBelow is an example `crifx.toml` file.\n```toml\n# Crifx configuration file example.\n\n# The github repository url for this problemset. This can be used to include\n# hyperlinks to GitHub Issues for each problem in the report.\ngithub_repo_url = \"https://github.com/FinnLidbetter/crifx\"\n\n# Section for defining minimum numbers of submissions and manual reviews.\n[review_requirements]\n# There must be AC submissions from at least 3 distinct judges.\nindependent_ac = 3\n# There must be at least 2 distinct language groups with at least one AC\n# submission written in a language in the group.\nlanguage_groups = 2\n# There must be at least one wrong_answer submission.\nsubmissions_wa = 1\n# There must be at least one time_limit_exceeded submission.\nsubmissions_tle = 1\n# There must be at least 3 judges who have reviewed the problem statement.\nstatement_reviewers = 3\n# There must be at least 2 judges who have reviewed the input validators.\nvalidator_reviewers = 2\n# There must be at least 2 judges who have reviewed the test data.\ndata_reviewers = 2\n\n# Define judge names in `[[judge]]` tables.\n[[judge]]\n# Primary name is required.\nprimary_name = \"Jane Doe\"\n# git_name is not required.\n# git_name = \"janedoe\"\n# Aliases is a list of zero or more alternative names.\naliases = [\"jd\", \"jane\"]\n\n[[judge]]\nprimary_name = \"Homer Simpson\"\ngit_name = \"homers123\"\naliases = []\n\n# Tables for defining language groups.\n[[language_group]]\n# Non alphanumeric characters can be used in the language group name.\nname = \"c/c++\"\n# The names of the languages in the group. Language names are cast to\n# lowercase before comparison to language names known to crifx.\nlanguages = [\"C\", \"C++\"]\n# The number of AC submissions required for this group.\nrequired_ac_count = 0\n\n[[language_group]]\nname = \"java/kotlin\"\nlanguages = [\"Java\", \"Kotlin\"]\nrequired_ac_count = 0\n\n[[language_group]]\nname = \"python\"\nlanguages = [\"Python\"]\nrequired_ac_count = 0\n```\nHere is an example `crifx-problem-status.toml` file inside the \n`examples/example_problemset/helloworld/` directory.\n```toml\n# GitHub Issue id number associated with this problem.\ngithub_issue_id = 1\n\n[review_status]\n# List of names of judges who have reviewed the problem statement.\nstatement_reviewed_by = [\n \"Alice\",\n \"Bob\",\n \"Jane Doe\",\n]\n# List of names of judges who have reviewed the input validator(s).\nvalidators_reviewed_by = [\n \"Homer Simpson\",\n]\n# List of names of judges who have reviewed the test data.\ndata_reviewed_by = [\n \"Homer Simpson\",\n \"Bob\",\n]\n```\n\nThis example report screenshot is produced from the example in `examples/example_problemset`\n\n\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Finn Lidbetter Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "icpc-style Contest pReparation Insights tool For anyone (X).",
"version": "0.1.4",
"project_urls": {
"Source": "https://github.com/FinnLidbetter/crifx"
},
"split_keywords": [
"icpc",
" contest",
" competitive programming",
" problemtools"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b7c53a65c7d7201f6fc5a16e620885a499dff3b28d9f4d3434307c401bb69ec1",
"md5": "a69e9b97e13b97defe8e698ca155236a",
"sha256": "73b15cf3f7333d6f03ebd6e35455531751fd3f83b9d3372148f9d609daeff9d4"
},
"downloads": -1,
"filename": "crifx-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a69e9b97e13b97defe8e698ca155236a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 26710,
"upload_time": "2024-11-04T04:08:26",
"upload_time_iso_8601": "2024-11-04T04:08:26.124738Z",
"url": "https://files.pythonhosted.org/packages/b7/c5/3a65c7d7201f6fc5a16e620885a499dff3b28d9f4d3434307c401bb69ec1/crifx-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2567285016a73a625e79bc57100417f80998f10a8a3b21456acb9ff8c7fe72e9",
"md5": "c164a05e704a2052e88d947b12d98f97",
"sha256": "69ac30f8fab9c95c3bf3e65c79ccb891f5a349fd096ae670c9047c44a063c79a"
},
"downloads": -1,
"filename": "crifx-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "c164a05e704a2052e88d947b12d98f97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 378052,
"upload_time": "2024-11-04T04:08:27",
"upload_time_iso_8601": "2024-11-04T04:08:27.873253Z",
"url": "https://files.pythonhosted.org/packages/25/67/285016a73a625e79bc57100417f80998f10a8a3b21456acb9ff8c7fe72e9/crifx-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-04 04:08:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FinnLidbetter",
"github_project": "crifx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "crifx"
}
