Skip to content

Admin docstrings#3569

Merged
arkid15r merged 11 commits intoOWASP:mainfrom
moizulfiqar:admin-docstrings
Jan 29, 2026
Merged

Admin docstrings#3569
arkid15r merged 11 commits intoOWASP:mainfrom
moizulfiqar:admin-docstrings

Conversation

@moizulfiqar
Copy link
Contributor

@moizulfiqar moizulfiqar commented Jan 26, 2026

Proposed change

Resolves #2651

This PR adds descriptive docstrings to methods within Django admin classes across backend/apps//admin/.py.
Files:
modified: backend/apps/owasp/admin/entity_channel.py
modified: backend/apps/owasp/admin/entity_member.py
modified: backend/apps/owasp/admin/member_profile.py
modified: backend/apps/owasp/admin/member_snapshot.py
modified: backend/apps/owasp/admin/mixins.py
modified: backend/apps/owasp/admin/project.py
modified: backend/apps/owasp/admin/project_health_metrics.py
modified: backend/apps/owasp/admin/widgets.py
modified: backend/apps/slack/admin/member.py

The docstrings document the purpose and return values of:
• Custom list display methods
• Custom admin filters
• Custom admin actions
• Overridden admin methods such as get_queryset

All docstrings follow the existing style used throughout the codebase, verified against other admin and model files.

Checks were run locally using make check-test, and no issues were found.

Checklist

  • Required: I followed the contributing workflow
  • Required: I verified that my code works as intended and resolves the issue as described
  • Required: I ran make check-test locally: all warnings addressed, tests passed
  • I used AI for code, documentation, tests, or communication related to this PR

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jan 26, 2026

Summary by CodeRabbit

Release Notes

  • New Features

    • Enhanced admin search functionality to discover members across Projects, Chapters, and Committees by name or key.
    • Improved member approval workflows with refined error handling for edge cases.
  • Bug Fixes

    • Fixed display of channel information and entity links in admin interfaces.
    • Corrected member approval logic to handle multiple suggested users appropriately.
  • Documentation

    • Added comprehensive documentation to admin methods for improved clarity.

✏️ Tip: You can customize this high-level summary in your review settings.

Walkthrough

This PR adds type hints and expands docstrings across multiple admin classes in OWASP and Slack applications, with targeted behavioral refinements to search and action methods.

Changes

Cohort / File(s) Summary
OWASP Entity Admin Classes
backend/apps/owasp/admin/entity_channel.py, backend/apps/owasp/admin/entity_member.py
Added type hints and expanded docstrings. entity_channel.py implements channel_search_display with Slack channel name resolution. entity_member.py extends get_search_results to query across Project/Chapter/Committee entities and adds approve_members action with entity/owasp_url display methods.
OWASP Member Admin Classes
backend/apps/owasp/admin/member_profile.py, backend/apps/owasp/admin/member_snapshot.py
Added return type annotations and comprehensive docstrings to get_queryset methods; preserved select_related optimization behavior.
OWASP Admin Infrastructure
backend/apps/owasp/admin/mixins.py, backend/apps/owasp/admin/widgets.py
mixins.py: Added type hints across BaseOwaspAdminMixin, GenericEntityAdminMixin, and StandardOwaspAdminMixin; introduced _format_github_link helper method for GitHub URL composition. widgets.py: Added type hints to ChannelIdWidget.init and render methods.
OWASP Display Methods
backend/apps/owasp/admin/project.py, backend/apps/owasp/admin/project_health_metrics.py
Added return type annotations and expanded docstrings for custom display field methods.
Slack Admin Member
backend/apps/slack/admin/member.py
Added return type annotation and expanded docstring to approve_suggested_users with branching logic handling single, multiple, and absent suggested users.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Suggested labels

backend

Suggested reviewers

  • kasya
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 inconclusive)
Check name Status Explanation Resolution
Title check ❓ Inconclusive The title 'Admin docstrings' is vague and generic, lacking specificity about what was added or changed to the admin docstrings. Consider a more descriptive title such as 'Add docstrings to Django admin methods across all apps' or 'Document admin methods with descriptive docstrings' to better convey the scope and purpose of the changes.
✅ Passed checks (4 passed)
Check name Status Explanation
Description check ✅ Passed The description clearly relates to the changeset, detailing the addition of docstrings to Django admin classes with specific files listed and objectives outlined.
Linked Issues check ✅ Passed The PR successfully addresses issue #2651 by adding descriptive docstrings to admin methods across multiple files, covering custom list display methods, admin filters, admin actions, and overridden methods like get_queryset().
Out of Scope Changes check ✅ Passed The changes include type hints and expanded docstrings to admin methods. While type hints go slightly beyond pure documentation, they serve the same documentation and maintainability goals and are minimally intrusive.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Fix all issues with AI agents
In `@backend/apps/github/models/mixins/repository.py`:
- Around line 184-193: The idx_subscribers_count property currently returns
stars_count which is incorrect; update the property (idx_subscribers_count) to
return the actual subscribers count (e.g., use self.subscribers_count or compute
len(self.subscribers) / appropriate field) and ensure the docstring remains
accurate; replace references to self.stars_count inside idx_subscribers_count
with the correct subscribers metric so indexing uses subscriber numbers not star
numbers.

In `@backend/apps/owasp/admin/member_snapshot.py`:
- Around line 110-122: Update the get_queryset docstring Returns section to
correctly state that the MemberSnapshot queryset uses
select_related('github_user') rather than saying it is "prefetched"; locate the
get_queryset method and change the Returns description to mention select_related
(or "related via select_related") to match the implementation and avoid implying
prefetch_related semantics.

In `@backend/apps/owasp/admin/mixins.py`:
- Around line 28-42: get_base_list_display currently calls tuple() with multiple
arguments which raises a TypeError; change it to build the return tuple via
concatenation: compute base = ("name",) if hasattr(self.model, "name") else ()
and return base + tuple(additional_fields) +
tuple(self.list_display_field_names), ensuring you reference
get_base_list_display, self.model, additional_fields, and
self.list_display_field_names.

Copy link
Collaborator

@arkid15r arkid15r left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please address merge conflicts and CR's comments.

@arkid15r arkid15r marked this pull request as draft January 26, 2026 23:55
coderabbitai[bot]
coderabbitai bot previously approved these changes Jan 27, 2026
Copy link
Contributor Author

@moizulfiqar moizulfiqar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @arkid15r, I have addressed CR's comments.

@moizulfiqar moizulfiqar marked this pull request as ready for review January 27, 2026 12:09
coderabbitai[bot]
coderabbitai bot previously approved these changes Jan 27, 2026
@moizulfiqar moizulfiqar requested a review from arkid15r January 27, 2026 12:20
Copy link
Contributor Author

@moizulfiqar moizulfiqar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All merge conflicts have also been resolved.

Copy link
Collaborator

@arkid15r arkid15r left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert unrelated changes and make sure PR covers all files under backend/apps/*/admin/

Copy link
Contributor Author

@moizulfiqar moizulfiqar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unrelated changes have been reverted (locally).

@arkid15r
Copy link
Collaborator

Unrelated changes have been reverted.

No they weren't

@arkid15r arkid15r marked this pull request as draft January 27, 2026 20:29
@moizulfiqar
Copy link
Contributor Author

moizulfiqar commented Jan 27, 2026

Thanks for the review @arkid15r.

I’ve reverted all unrelated changes and ensured this PR consistently covers only the admin files under backend/apps/*/admin/. The following files were altered, and all are within the intended scope:

backend/apps/api/admin/init.py DONE
backend/apps/api/admin/api_key.py DONE
backend/apps/core/admin/init.py DONE
backend/apps/core/admin/prompt.py DONE
backend/apps/github/admin/init.py DONE
backend/apps/github/admin/comment.py DONE
backend/apps/github/admin/commit.py DONE
backend/apps/github/admin/issue.py DONE
backend/apps/github/admin/label.py DONE
backend/apps/github/admin/milestone.py DONE
backend/apps/github/admin/organization.py DONE
backend/apps/github/admin/pull_request.py DONE
backend/apps/github/admin/release.py DONE
backend/apps/github/admin/repository.py DONE
backend/apps/github/admin/repository_contributor.py DONE
backend/apps/github/admin/user.py DONE
backend/apps/mentorship/admin/init.py DONE
backend/apps/mentorship/admin/issue_user_interest.py DONE
backend/apps/mentorship/admin/mentee.py DONE
backend/apps/mentorship/admin/mentee_module.py DONE
backend/apps/mentorship/admin/mentee_program.py DONE
backend/apps/mentorship/admin/mentor.py DONE
backend/apps/mentorship/admin/module.py DONE
backend/apps/mentorship/admin/program.py DONE
backend/apps/mentorship/admin/task.py DONE
backend/apps/mentorship/admin/task_level.py DONE
backend/apps/nest/admin/init.py DONE
backend/apps/nest/admin/badge.py DONE
backend/apps/nest/admin/user.py DONE
backend/apps/nest/admin/user_badge.py DONE
backend/apps/owasp/admin/init.py DONE
backend/apps/owasp/admin/board_of_directors.py DONE
backend/apps/owasp/admin/chapter.py DONE
backend/apps/owasp/admin/committee.py DONE
backend/apps/owasp/admin/entity_channel.py DONE
backend/apps/owasp/admin/entity_member.py DONE
backend/apps/owasp/admin/event.py DONE
backend/apps/owasp/admin/member_profile.py DONE
backend/apps/owasp/admin/member_snapshot.py DONE
backend/apps/owasp/admin/mixins.py DONE
backend/apps/owasp/admin/post.py DONE
backend/apps/owasp/admin/project.py DONE
backend/apps/owasp/admin/project_health_metrics.py DONE
backend/apps/owasp/admin/snapshot.py DONE
backend/apps/owasp/admin/sponsor.py DONE
backend/apps/owasp/admin/widgets.py DONE
backend/apps/slack/admin/init.py DONE
backend/apps/slack/admin/conversation.py DONE
backend/apps/slack/admin/event.py DONE
backend/apps/slack/admin/member.py DONE
backend/apps/slack/admin/message.py DONE
backend/apps/slack/admin/workspace.py DONE

I appreciate your patience in reviewing this and would be grateful if you could kindly review the changes again to confirm everything is in order. I’ll make sure the quality of my work remains consistent going forward.

@moizulfiqar moizulfiqar requested a review from arkid15r January 27, 2026 21:47
@moizulfiqar moizulfiqar marked this pull request as ready for review January 28, 2026 11:48
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
backend/apps/slack/admin/member.py (1)

47-51: Typo: Leading space in success message.

Line 49 has a leading space in the message string: " assigned user for {entity}." — should likely be "Assigned user for {entity}." or "Successfully assigned user for {entity}.".

Proposed fix
                 self.message_user(
                     request,
-                    f" assigned user for {entity}.",
+                    f"Assigned user for {entity}.",
                     messages.SUCCESS,
                 )
🧹 Nitpick comments (1)
backend/apps/slack/admin/member.py (1)

41-64: Avoid duplicate count() queries per entity.

suggestions.count() is called twice per iteration (lines 44 and 52), each triggering a separate database query. Cache the count to eliminate redundant queries.

♻️ Proposed fix
         for entity in queryset:
             suggestions = entity.suggested_users.all()
+            suggestions_count = suggestions.count()

-            if suggestions.count() == 1:
+            if suggestions_count == 1:
                 entity.user = suggestions.first()  # only one suggested user
                 entity.save()
                 self.message_user(
                     request,
                     f" assigned user for {entity}.",
                     messages.SUCCESS,
                 )
-            elif suggestions.count() > 1:
+            elif suggestions_count > 1:
                 self.message_user(
                     request,
                     f"Error: Multiple suggested users found for {entity}. "
                     f"Only one user can be assigned due to the one-to-one constraint.",
                     messages.ERROR,
                 )
             else:

@arkid15r arkid15r enabled auto-merge January 29, 2026 07:38
@sonarqubecloud
Copy link

@codecov
Copy link

codecov bot commented Jan 29, 2026

Codecov Report

❌ Patch coverage is 82.75862% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.56%. Comparing base (d952711) to head (d2a4a6e).
⚠️ Report is 3 commits behind head on main.

Files with missing lines Patch % Lines
backend/apps/owasp/admin/mixins.py 70.00% 3 Missing ⚠️
backend/apps/owasp/admin/member_profile.py 66.66% 1 Missing ⚠️
backend/apps/owasp/admin/member_snapshot.py 66.66% 1 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #3569      +/-   ##
==========================================
+ Coverage   85.55%   85.56%   +0.01%     
==========================================
  Files         463      463              
  Lines       14302    14306       +4     
  Branches     1903     1903              
==========================================
+ Hits        12236    12241       +5     
+ Misses       1687     1686       -1     
  Partials      379      379              
Flag Coverage Δ
backend 84.55% <82.75%> (+0.01%) ⬆️
frontend 88.38% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
backend/apps/owasp/admin/entity_channel.py 60.00% <100.00%> (+1.37%) ⬆️
backend/apps/owasp/admin/entity_member.py 63.41% <100.00%> (+0.91%) ⬆️
backend/apps/owasp/admin/project.py 93.33% <ø> (ø)
backend/apps/owasp/admin/project_health_metrics.py 90.90% <100.00%> (ø)
backend/apps/owasp/admin/widgets.py 100.00% <100.00%> (ø)
backend/apps/slack/admin/member.py 100.00% <100.00%> (ø)
backend/apps/owasp/admin/member_profile.py 92.30% <66.66%> (+7.69%) ⬆️
backend/apps/owasp/admin/member_snapshot.py 92.85% <66.66%> (+7.14%) ⬆️
backend/apps/owasp/admin/mixins.py 53.33% <70.00%> (-0.10%) ⬇️

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d952711...d2a4a6e. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@arkid15r arkid15r added this pull request to the merge queue Jan 29, 2026
Merged via the queue into OWASP:main with commit 50115b0 Jan 29, 2026
33 of 35 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add Docstrings to Admin Class Methods

2 participants

Comments