Initial commit

.devcontainer/devcontainer.json

@@ -0,0 +1,14 @@
+{
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.11-bookworm",
+	"postCreateCommand": "/bin/bash -c 'python -m pip install poetry && python -m poetry install & git clone https://github.com/dot-agent/nextpy-examples; wait'",
+	"forwardPorts": [3000, 8000],
+	"portsAttributes": {
+		"3000": {
+			"label": "Frontend",
+			"onAutoForward": "notify"
+		},
+		"8000": {
+			"label": "Backend"
+		}
+	}
+}

.coveragerc

@@ -0,0 +1,31 @@
+[run]
+source = 
+branch = true
+
+[report]
+show_missing = true
+# TODO bump back to 79
+fail_under = 75
+precision = 2
+
+# Regexes for lines to exclude from consideration
+exclude_also =
+    # Don't complain about missing debug-only code:
+    def __repr__
+    if self\.debug
+
+    # Don't complain if tests don't hit defensive assertion code:
+    raise AssertionError
+    raise NotImplementedError
+
+    # Don't complain if non-runnable code isn't run:
+    if 0:
+    if __name__ == .__main__.:
+
+    # Don't complain about abstract methods, they aren't run:
+    @(abc\.)?abstractmethod
+
+ignore_errors = True
+
+[html]
+directory = coverage_html_report

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,89 @@
+name: "\U0001F41B Bug Report"
+description: Submit a bug report to help us improve nextpy. To report a security issue, please instead use the security option.
+labels: ["02 Bug Report"]
+body:
+  - type: markdown
+    attributes:
+      value: >
+        We appreciate the time you are taking to file a bug report to help us enhance nextpy.
+        Please take a moment to search the issue tracker for existing issues before posting
+        a new one to prevent duplicates. Thank you for your contribution!
+
+  - type: textarea
+    id: system-info
+    attributes:
+      label: System Info
+      description: Provide the details of your operating environment.
+      placeholder: nextpy version, platform version, Python version, browser and version (if relevant), etc.
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: related-components
+    attributes:
+      label: Related Components
+      description: "Which components seem to be related to the issue?"
+      options:
+        - label: "Markup & UI Components"
+        - label: "Database Integrations"
+        - label: "API Servers / Endpoints"
+        - label: "Routing Mechanics"
+        - label: "Plugin System"
+        - label: "Data Validation and Serialization"
+        - label: "Authentication Systems"
+        - label: "Developer Tools and Scripts"
+        - label: "Performance and Scalability"
+        - label: "Documentation or Examples"
+        - label: "Configuration"
+        - label: "Tests or Test Framework"
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: |
+        We need a well-defined, step-by-step guide or code snippet that reproduces the said issue....
+        For code blocks and proper formatting, kindly refer to https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks
+
+    validations:
+      required: true
+
+    placeholder: |
+      Provide clear steps or code to repeat the observed bug:
+
+        1.
+        2.
+        3.
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: Generally tell us what should happen instead of the bug you've encountered.
+
+    validations:
+      required: true
+
+      placeholder: 'Detail out the norm desperately hoped to be witnessed upon following through your procedure:'
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: What Actually Happened
+      description: Highlight what went wrong insofar as divergences from the presupposed occurrences are viewed.
+      placeholder: "Instead of the expected outcome, explain the troublesome reality."
+
+    validations:
+      required: true
+
+  - type: markdown
+    id: troubleshooting
+    attributes:
+      value: |
+        Please shed some light on attempts towards issue mitigation, previous utilities hadn_receiver herald success, or secondary incongruities formalized gab_job seg_index poorly decor. For instance shops, professional.stdout_loop proverb wreck_array reflectsениe busy_icon tel_item falling_active utilizing CIOLayer priceless_ensemble toolbox getPath blank lookahead mined Q.I.outline.
+      
+  - type: checkboxes
+    id: troubleshooting-steps
+    attributes:
+      label: Troubleshooting Steps Attempted
+      description: "What different options have you tried to resolve this issue already?"

.github/actions/setup_build_env/action.yml

@@ -0,0 +1,108 @@
+# Entry conditions:
+# - `setup/checkout` has already happened
+# - working dir is the root directory of your project (e.g. `nextpy/`).
+# - You have a `poetry.lock` file in the root directory of your project
+# - You have a `pyproject.toml` file in the root directory of your project
+#
+# Exit conditions:
+# - Python of version `python-version` is ready to be invoked as `python`.
+# - Poetry of version `poetry-version` is ready ot be invoked as `poetry`.
+# - If `run-poetry-install` is true, deps as defined in `pyproject.toml` will have been installed into the venv at `create-venv-at-path`.
+
+name: 'Setup Nextpy build environment'
+description: 'Sets up Python, install poetry (cached), install project deps (cached)'
+inputs:
+  python-version:
+    description: 'Python version setup'
+    required: true
+  poetry-version:
+    description: 'Poetry version to install'
+    required: false
+    default: '1.3.1'
+  run-poetry-install:
+    description: 'Whether to run poetry install on current dir'
+    required: false
+    default: false
+  create-venv-at-path:
+    description: 'Path to venv (if poetry install is enabled)'
+    required: false
+    default: '.venv'
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python ${{ inputs.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    # This is required for OS portability in presence of caching.
+    #
+    # The act of installing poetry has the side effect of adding
+    # poetry bin path to system path.
+    #
+    # But, if we get a cache hit on the poetry installation, we
+    # don't get this important side effect. As a result, bare calls
+    # to "poetry" fails.
+    - name: Prepare PATH env to include where poetry will be installed into
+      shell: bash
+      run: |
+        echo "~/.local/bin/" >> $GITHUB_PATH
+
+    - name: Restore cached poetry install
+      id: restore-poetry-cache
+      uses: actions/cache/restore@v3
+      with:
+        path: ~/.local
+        key: ${{ runner.os }}-python-${{ inputs.python-version }}-poetry-${{ inputs.poetry-version }}
+
+    - if: steps.restore-poetry-cache.outputs.cache-hit != 'true'
+      name: Install Poetry
+      uses: snok/install-poetry@v1
+      with:
+        version: ${{ inputs.poetry-version }}
+        virtualenvs-create: true
+        virtualenvs-in-project: true
+        virtualenvs-path: ${{ inputs.create-venv-at-path }}
+
+    - if: steps.restore-poetry-cache.outputs.cache-hit != 'true'
+      name: Save poetry install to cache
+      uses: actions/cache/save@v3
+      with:
+        path: ~/.local
+        key: ${{ steps.restore-poetry-cache.outputs.cache-primary-key }}
+
+    - name: Restore cached project python deps
+      id: restore-pydeps-cache
+      uses: actions/cache/restore@v3
+      with:
+        path: ${{ inputs.create-venv-at-path }}
+        key: ${{ runner.os }}-python-${{ inputs.python-version }}-pydeps-${{ hashFiles('**/poetry.lock') }}
+
+    - if: ${{ inputs.run-poetry-install == 'true' && steps.restore-pydeps-cache.outputs.cache-hit != 'true' }}
+      name: Run poetry install (will get cached)
+      # We skip over installing the root package (the current project code under CI)
+      # Root package should not be cached - its content is not reflected in poetry.lock / cache key
+
+      # On Windows, it is scripts/activate. On Linux and MacOS, it is bin/activate
+      shell: bash
+      run: |
+        python -m venv ${{ inputs.create-venv-at-path }}
+        source ${{ inputs.create-venv-at-path }}/*/activate
+        poetry install --no-interaction --no-root
+
+    - if: steps.restore-pydeps-cache.outputs.cache-hit != 'true'
+      name: Save Python deps to cache
+      uses: actions/cache/save@v3
+      with:
+        path: ${{ inputs.create-venv-at-path }}
+        key: ${{ steps.restore-pydeps-cache.outputs.cache-primary-key }}
+
+    - if: ${{ inputs.run-poetry-install == 'true' }}
+      name: Run poetry install (root package)
+      # Here we really install the root package (the current project code under CI).env:
+      # This should not be cached.
+      shell: bash
+      run: |
+        source ${{ inputs.create-venv-at-path }}/*/activate
+        poetry install --only-root --no-interaction

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+<!-- 
+
+We appreciate your contribution to next.py! 
+
+Replace this entire comment with:
+- **Description:** A clear and concise summary of your changes.
+- **Issue:** Reference the issue number this PR addresses, if applicable.
+- **Dependencies:** List any new dependencies necessitated by your contribution.
+- **Tag Maintainer:** If you're seeking prompt feedback, please tag (@) the appropriate maintainer from the team.
+- **Social Handle (Twitter/Discord):** When we feature significant updates on social media and you'd like to be mentioned, share your username so that we can give you proper credit!
+
+Ensure your pull request meets our standards for linting and testing before submitting. Locally execute `make format`, `make lint`, and `make test` to verify.
+
+Further guidance on how to run tests, check linting, and more, are found in our contribution guidelines here: 
+[Contribution Guidelines](https://github.com/dot-agent/nextpy/blob/master/.github/CONTRIBUTING.md)
+
+Should you find that your PR has not been reviewed after a few days, feel free to leave a message for either @anubrag or another available maintainer for assistance.
+
+ -->

.github/workflows/check_generated_pyi.yml

@@ -0,0 +1,33 @@
+name: check-generated-pyi
+
+on:
+  push:
+    branches: [ "main" ]
+    # We don't just trigger on pyi_generator.py and the components dir, because
+    # there are other things that can change the generator output
+    # e.g. black version, nextpy.Component, nextpy.Var.
+    paths-ignore:
+      - '**/*.md'
+  pull_request:
+    branches: [ "main" ]
+    paths-ignore:
+      - '**/*.md'
+
+jobs:
+  check-generated-pyi-components:
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup_build_env
+        with:
+          python-version: "3.11.5"
+          run-poetry-install: true
+          create-venv-at-path: .venv
+      - run: |
+          poetry run python scripts/pyi_generator.py
+          if git diff; then
+            echo "No diffs - AOK!"
+          else
+            echo "ERROR: pyi_generator.py output is out of date. Please run scripts/pyi_generator.py and commit the changes."
+          fi

.github/workflows/integration_app_harness.yml

@@ -0,0 +1,55 @@
+name: integration-app-harness
+
+on:
+  push:
+    branches: [ "main" ]
+    paths-ignore:
+      - '**/*.md'
+  pull_request:
+    branches: [ "main" ]
+    paths-ignore:
+      - '**/*.md'
+
+permissions:
+  contents: read
+
+jobs:
+  integration-app-harness:
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        state_manager: [ "redis", "memory" ]
+    runs-on: ubuntu-latest
+    services:
+      # Label used to access the service container
+      redis:
+        image: ${{ matrix.state_manager == 'redis' && 'redis' || '' }}
+        # Set health checks to wait until redis has started
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          # Maps port 6379 on service container to the host
+          - 6379:6379
+    steps:
+    - uses: actions/checkout@v4
+    - uses: ./.github/actions/setup_build_env
+      with:
+          python-version: "3.11.5"
+          run-poetry-install: true
+          create-venv-at-path: .venv
+    - run: poetry run pip install pyvirtualdisplay pillow
+    - name: Run app harness tests
+      env:
+        SCREENSHOT_DIR: /tmp/screenshots
+        REDIS_URL: ${{ matrix.state_manager == 'redis' && 'localhost:6379' || '' }}
+      run: |
+        poetry run pytest integration
+    - uses: actions/upload-artifact@v3
+      name: Upload failed test screenshots
+      if: always()
+      with:
+        name: failed_test_screenshots
+        path: /tmp/screenshots