{"id":18518329,"url":"https://github.com/arxiv/arxiv-base","last_synced_at":"2025-04-09T08:31:35.666Z","repository":{"id":27167128,"uuid":"108022423","full_name":"arXiv/arxiv-base","owner":"arXiv","description":"Supporting libraries for templates and arXiv services","archived":false,"fork":false,"pushed_at":"2024-05-21T17:31:56.000Z","size":7434,"stargazers_count":27,"open_issues_count":7,"forks_count":8,"subscribers_count":14,"default_branch":"develop","last_synced_at":"2024-05-22T16:44:44.316Z","etag":null,"topics":["flask","in-production","python"],"latest_commit_sha":null,"homepage":"https://arxiv.github.io/arxiv-base/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arXiv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-23T18:27:06.000Z","updated_at":"2024-05-29T17:32:55.524Z","dependencies_parsed_at":"2023-10-14T15:40:49.251Z","dependency_job_id":"d976fc84-bded-49d6-9110-a6d28a315226","html_url":"https://github.com/arXiv/arxiv-base","commit_stats":null,"previous_names":[],"tags_count":125,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arXiv%2Farxiv-base","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arXiv%2Farxiv-base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arXiv%2Farxiv-base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arXiv%2Farxiv-base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arXiv","download_url":"https://codeload.github.com/arXiv/arxiv-base/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248003140,"owners_count":21031739,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flask","in-production","python"],"created_at":"2024-11-06T17:12:55.451Z","updated_at":"2025-04-09T08:31:35.659Z","avatar_url":"https://github.com/arXiv.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# arXiv Base\n\nThis project provides a base Flask application and base Docker image for\narXiv-NG services.\n\nEach component of this project **must** meet all the following criteria:\n\n1. It is likely that the component will be utilized in many or all arXiv\n   services.\n2. Once stable, it is unlikely to change often.\n3. It is unlikely that implementing new features in specific services\n   would require changes to the component.\n4. When a component does change, it **must** change in the same way for all    the services that use it.\n\n## Base CSS and Templates for arXiv.org-NG\n\nTemplates are written in [Jinja2 syntax](http://jinja.pocoo.org/docs/2.9/). CSS\nframework is [Bulma](http://bulma.io) with arXiv-specific overrides for color\nand typography. While the .sass format has been used for override files, .scss\nfiles may also be imported and included.\n\nThese files set the default display styles and layout for all pages on\narxiv-NG, and can be overridden as needed by submodules.\n\nA template is included for rapid evaluation of display layer CSS within this\nrepo, prepopulated with sample content.\nThe ``styleguide.html`` template (route: /styleguide) shows error message\nsamples, informational message boxes, and sample content from search.\n\n## Development server\n\nThis project includes a minimal Flask application for development\nverification/testing purposes. To run the dev server (assuming that you are\nworking in the root of this repository):\n\n```bash\npoetry install\n$ FLASK_APP=app.py FLASK_DEBUG=1 poetry run flask run\n```\n\nYou should be able to view the rendered ``styleguide.html`` at\n``http://127.0.0.1:5000/styleguide``.\n\n## Installing `arxiv-base`\n\nTo use the base package in a Flask application add it to your\ndependency manager.  To use a specific version, for example, you would write:\n\n``arxiv-base = \"==0.11.1rc5\"``\n\nOr if you want to install a specific working branch (dev only) the line\nmight read:\n\n``arxiv-base = {git = \"https://github.com/arXiv/arxiv-base.git@task/ARXIVNG-1215\"}``\n\nYou can use ``pip`` from the command line to install a selected\nunpublished branch. First uninstall existing, then reinstall using pip\nsyntax above.  Example:\n\n```bash\npip uninstall arxiv-base\npip install git+https://github.com/arXiv/arxiv-base.git@task/ARXIVNG-1010#egg=arxiv-base\n```\n\n## Using `arxiv-base` with Flask\n\nIn your application factory, instantiate the Base component. This makes\ntemplates and static files available to you. For example, in your\n``factory.py`` module:\n\n```python\nfrom flask import Flask\nfrom arxiv.base import Base\n\ndef create_web_app() -\u003e Flask:\n   app = Flask('mega_tool')\n   app.config.from_pyfile('config.py')\n\n   Base(app)   # Registers the base/UI blueprint.\n   @app.route(\"/mega_tool\")\n   def mega_tool():\n       # TODO use something from arxiv-base \n       return \"\u003cp\u003eMega_tool!\u003c/p\u003e\"\n\n   return app\n```\n\nYou can now extend base templates, e.g.:\n\n```html\n{%- extends \"base/base.html\" %}\n\n{% block content %}\nHello world!\n{% endblock %}\n```\n\nAnd use static files in your templates, e.g.:\n\n```\n{{ url_for('base.static', filename='images/CUL-reduced-white-SMALL.svg') }}\n```\n\n## Static files and paths\n\nIn order to serve static assets for multiple versions of the app at\nthe same time, arxiv-base prefixes the app name and app version to\nasset urls. This is to allow gracefully upgrades with no broken links\nto css, js or images.\n\nThe ``Base`` component will automatically set your app's\n[``static_url_path``](http://flask.pocoo.org/docs/1.0/api/#flask.Flask.static_url_path)\nusing the name of the app and the value of ``APP VERSION`` in your\nconfig to ``/static/[app name]/[ app version ]``. It will also rewrite\nblueprint\n[``static_url_path``](http://flask.pocoo.org/docs/1.0/api/#flask.Blueprint.static_url_path)\nto ``/static/[app name]/[ app version ]/[ blueprint name]``.\n\n### Serving static files on S3\nWe use [Flask-S3](https://flask-s3.readthedocs.io/en/latest/) to serve static\nfiles via S3. To deploy the assets for the current version:\n\n  pip install ./\n  AWS_ACCESS_KEY_ID=x \\\n  AWS_SECRET_ACCESS_KEY=x+3RcGf1Oul66cwSJbZZcdZdEv0ZC9ax2 \\\n  AWS_REGION=us-east-1 FLASKS3_BUCKET_NAME=arxiv-web-static1 \\\n  python upload_static_assets.py\n\nBe sure to initialize the integration after instantiating ``Base`` and\nregistering your blueprints. For example:\n\n```python\n# TODO just have a s3 script\n# def create_web_app() -\u003e Flask:\n#     \"\"\"Initialize and configure the application.\"\"\"\n# \n#     app = Flask('cool_app')\n#     app.config.from_object(config)\n#     Base(app)    # Gives us access to the base UI templates and resources.\n#     app.register_blueprint(routes.blueprint)\n#     s3.init_app(app)    # \u003c- Down here!\n#     return app\n```\n\n## App tests\n\nSome tests to check app configuration and pattern compliance are provided in\n``arxiv.base.tests``. See that module for usage. You can run them with the command ``pytest``\n\n## Editing and compiling sass\n\nThe file `arxivstyle.css` should never be edited directly. It is compiled from\n`arxivstyle.sass` with this command from project directory root:\n``sass arxiv/base/static/sass/arxivstyle.sass:arxiv/base/static/css/arxivstyle.css``\n\nor you can use the ``--watch`` option to autocompile on any changed file:\n\n``sass --watch arxiv/base/static/sass/arxivstyle.sass:arxiv/base/static/css/arxivstyle.css``\n\nBulma source files are included in the ``static/sass`` directory so that\nvariables can be overridden directly during compile. The ``arxivstyle.sass``\nfile has been written to do this; do not edit it.\n\n[Documentation for sass](http://sass-lang.com/documentation/file.SASS_REFERENCE.html)\n\n## Layout features, tips and tricks\n\n### Beta watermark\n\nAdding ``class=\"beta\"`` to the main content div will create a beta watermark at\n the top left of pages having this class.\n\n## Upload to pypi\n\n```bash\npip install --upgrade setuptools wheel twine\npython setup.py sdist bdist_wheel\ntwine --upload dist/*  # Enter username and password from lastpass\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farxiv%2Farxiv-base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farxiv%2Farxiv-base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farxiv%2Farxiv-base/lists"}