Skip to content

Instantly share code, notes, and snippets.

@nebiyuelias1

nebiyuelias1/django_stubs_proposal_draft.md

Last active March 29, 2024 15:40
Show Gist options
  • Save nebiyuelias1/456644a00deefd45fb2396967cee3d26 to your computer and use it in GitHub Desktop.
Save nebiyuelias1/456644a00deefd45fb2396967cee3d26 to your computer and use it in GitHub Desktop.
Download ZIP
GSOC 2024 Proposal Draft
Raw
django_stubs_proposal_draft.md

Table of Contents

  1. Abstract
  2. The Solution
  3. Schedule and Milestones
  4. About Me

Abstract

Overview

The django-stubs project aims to enhance Django development by adding comprehensive type hints, allowing static type checkers like Mypy to identify potential errors early in the development process. However, the current coverage of type hints in django-stubs is not exhaustive, especially concerning approximately 1600 missing type hints. This proposal seeks to address this issue by expanding django-stubs coverage through Google Summer of Code 2024. There's a new release planned for Django 5.0 (#2020). With this, we can have a better typing support for the next release.

Goals

The primary goal is to enhance django-stubs by adding type hints for a specific, significant subset of the ~1600 missing functions and classes. This includes improving type coverage for core Django functionalities, models, forms, views, and ORM operations.

At the moment, there are discrepancies between the stubs and the implementation. That's why we have 3 different files that instruct stubtest to ignore the discrepancies. Otherwise, the tool would report a lot of errors. These files are:

  • scripts/stubtest/allowlist.txt: where we store things that we really don't care about: hacks, django internal utility modules, things that are handled by our plugin, things that are not representable by type system, etc
  • scripts/stubtest/allowlist_todo.txt: where we store all errors there are right now. Basically, this is a TODO list: we need to work through this list and fix things (or move entries to real allowlist.txt). In the end, ideally we can remove this file
  • scripts/stubtest/allowlist_todo_django50.txt: Only discrepancies that appeared after Django 4.2 -> 5.0 update. There are real problems we should fix and things we can really ignore.

Right now, the “todo” list contains ~1600 functions and classes missing type hints. The goal is to significantly reduce the two "todo" allowlists, i.e., allowlist_todo.txt and allowlist_todo_django50.txt. For things that can absolutely be ignored we can move them to the allowlist.txt file. This way our stubs would mirror the actual implementation and we would have have a better typing support.

Benefits

  • Enhances Django development by providing comprehensive type hints.
  • Improves code quality and maintainability.
  • Facilitates better IDE support and code navigation.
  • The divergence between the stubs and the actual implementation would be minimized.

The Solution

This project will focus on systematically expanding type hint coverage in django-stubs. I will collaborate with the Django development community to identify areas within the framework that currently lack sufficient type annotations. Here's the proposed approach:

  1. Analysis and Prioritization:
  • Identify missing stubs from the todos allowlist.txt file.
  • Prioritize based on significance and impact.
  1. Stub Addition:
  • Begin with foundational Django components (e.g., models, forms).
  • Implement type hints for ORM operations, views, and serializers.
  • Ensure compatibility and adherence to Django's coding standards.
  1. Testing and Validation:
  • Utilize Mypy and stubtest for validation.
  • Implement thorough unit tests for added type hints.
  • Ensure compatibility across different Django versions.
  1. Documentation:
  • Document added type hints comprehensively.
  • Provide examples and usage guidelines for developers.
  • Update contributing guidelines for future contributors.

Schedule and Milestones

  • Community Bonding Period (May 1 - May 26):

    • Engage with mentors and community for guidance.
    • Conduct in-depth analysis of the django-stubs project structure and requirements.

  • Phase 1: Stub Analysis and Prioritization (May 27 - June 10):

    • Analyze todos allowlist.txt file to identify missing stubs.
    • Prioritize missing stubs based on significance and impact.
    • Create a roadmap for stub addition based on priority.

  • Phase 2: Stub Addition (June 11 - July 8):

    • Begin adding type hints for prioritized missing stubs.
    • Implement type hints for core Django models and forms.
    • Ensure compatibility and adherence to Django's coding standards.

  • Midterm Evaluation Period (July 8 - July 12):

    • Prepare and submit midterm evaluation.

  • Phase 3: Testing and Validation (July 12 - August 4):

    • Utilize Mypy and stubtest for validation of added type hints.
    • Implement thorough unit tests for newly added type hints.
    • Validate compatibility across different Django versions.

  • Phase 4: Documentation and Finalization (August 5 - August 19):

    • Document added type hints comprehensively.
    • Provide examples and usage guidelines for developers.
    • Update contributing guidelines for future contributors.

  • Final Work Submission Period (August 19 - August 26):

    • Prepare and submit final work product.
    • Submit final mentor evaluation.

About Me

My name is Nebiyu Elias and I'm currently doing my masters degree in computer science at Taiwan Tech in Taiwan. I recently was doing intership at ASUS. Prior to this I've been working in the industry as a software engineer and have held various positions over the last 5 years. As far as my experience with Django goes, I was a big fan of this framework ever since my university days. I've also worked on big project that used django, DRF, and django-channels. The project allowed me to better understand the philosophy of Django and it's inner workings.

Now, I want to contribute and get involved with open source. That's why I'm applying to GSOC 2024. I think it can allow me to have a good start and leverage my previous experience to contribute to the community.

4.1 Past contributions to Django

I have been using Django and other packages related to it over the years and here're some evidence to support my claim

4.1.1 Issues

4.1.2 Pull Requests

4.2 Personal Details

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment