portfolio-package 0.1.0__tar.gz

portfolio_package-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 puzzllium
+
+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.

portfolio_package-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: portfolio-package
+Version: 0.1.0
+Summary: Portfolio site package for the Core boilerplate (projects, skills, education, certifications, services, social links). Depends on core-package for auth, RBAC, and the shared User model — it does not define its own.
+Author-email: puzzllium <puzzllium@gmail.com>
+Maintainer-email: puzzllium <puzzllium@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/puzzelchannel/portfolio-package
+Project-URL: Issues, https://github.com/puzzelchannel/portfolio-package/issues
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: core-package
+Requires-Dist: blog-package
+Requires-Dist: django-ninja>=1.7.0
+Requires-Dist: django-unfold>=0.81.0
+Requires-Dist: Pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-django>=4.14; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4; extra == "dev"
+Dynamic: license-file
+
+# portfolio-package
+
+A portfolio site package for the [Core](../../Core) boilerplate: projects
+(with an image gallery), skills, education, certifications, services, social
+links, and a `Profile` (the About/hero content — headline, tagline, bio,
+stat-box numbers). It depends on [core-package](https://pypi.org/project/core-package/) for auth, RBAC,
+and the shared `User` model — **it never defines its own user/account
+model**; every record here is owned by a Core `User` via
+`settings.AUTH_USER_MODEL`. A user's *name* and *profile picture* live on
+Core's own `User` model (`first_name`/`last_name`/`avatar`), not here.
+
+Also depends on `blog-package` — this site's About/portfolio pages include a
+blog section, so installing `portfolio` installs `blog` too (see "Installing
+into a Core-based project" below).
+
+`Project.title`/`summary`/`description` and `Profile.headline`/`tagline`/
+`bio` are translatable via `apps.core.models.TranslatableModel` — a single
+`translations` JSON field per row (`{"fa": {"title": "...", ...}, "de":
+{...}}`), not a `title_en`/`title_fa` column per language. Add a language by
+calling `PUT /projects/{id}/translations/{language}` or
+`PUT /profile/me/translations/{language}`, no migration required.
+
+See Core's `AGENT.md` §10 ("Package architecture") for the full contract this
+package follows.
+
+## Installation
+
+```bash
+pip install portfolio-package
+```
+
+Requires Python 3.10+ and Django 5.2 (via core-package). This also installs
+`blog-package`.
+
+## Local development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e /path/to/Core/Core   # core-package, editable
+pip install -e ".[dev]"
+pytest
+```
+
+## Installing into a Core-based project
+
+1. Install it into the host repo's venv:
+   ```bash
+   pip install portfolio-package
+   ```
+   This also pulls in `blog-package`. You still need to do steps 2-4 for
+   **both** `portfolio` and `blog` — Core's "no auto-discovery, explicit
+   wiring" convention (§10) means the pip install is automatic, but
+   `INSTALLED_APPS`/router-mounting/`migrate` are not; see `blog`'s own
+   README for its exact `INSTALLED_APPS`/router lines. For local development
+   of either package, install it editable instead
+   (`pip install -e ../Packages/portfolio-package`).
+2. Add it to `INSTALLED_APPS` in the host's `config/settings/base.py`, under
+   the `# site packages` comment (after the local apps block):
+   ```python
+   # site packages
+   "blog",
+   "portfolio",
+   ```
+3. Mount its router in the host's `config/api.py`:
+   ```python
+   from blog.api import router as blog_router
+   from portfolio.api import router as portfolio_router
+   ...
+   api.add_router("/blog", blog_router)
+   api.add_router("/portfolio", portfolio_router)
+   ```
+   Since both are wildcard-free routers, order relative to the other
+   `add_router` calls doesn't matter.
+4. Migrate:
+   ```bash
+   python manage.py migrate
+   ```
+5. Optional — add a nav entry under `UNFOLD["SIDEBAR"]["navigation"]` in the
+   host's `config/settings/base.py` for its admin models (`Project`, `Profile`,
+   `Skill`, etc., and `blog`'s `Post`, `Comment`, etc.).
+
+## Endpoints
+
+Mounted at whatever prefix the host chooses (`/portfolio` in the example
+above):
+
+- `GET /projects` — paginated list of published projects (public), optional
+  `?user_id=` and `?lang=`
+- `GET /projects/by-slug/{slug}` — published project detail (public),
+  optional `?lang=`
+- `GET /profile?user_id=` — a user's About/hero content (public), optional
+  `?lang=`
+- `GET /skills`, `/services`, `/education`, `/certifications`,
+  `/social-links` — public read-only lists, optionally filtered by
+  `?user_id=`
+- `POST /projects`, `GET /projects/{project_id}`,
+  `PATCH /projects/{project_id}`, `DELETE /projects/{project_id}` —
+  admin-only (`require_role("admin")`, from Core)
+- `PUT /projects/{project_id}/translations/{language}` — admin-only; sets
+  the translated `title`/`summary`/`description` for that language
+- `PATCH /profile/me` — admin-only; create/update the caller's own `Profile`
+- `PUT /profile/me/translations/{language}` — admin-only; sets the
+  translated `headline`/`tagline`/`bio` for that language
+
+Skills/education/certifications/services/social-links/project images are
+managed through the Django admin (no write API for them yet —
+deliberately, to avoid building endpoints nothing needs yet).

portfolio_package-0.1.0/README.md

@@ -0,0 +1,108 @@
+# portfolio-package
+
+A portfolio site package for the [Core](../../Core) boilerplate: projects
+(with an image gallery), skills, education, certifications, services, social
+links, and a `Profile` (the About/hero content — headline, tagline, bio,
+stat-box numbers). It depends on [core-package](https://pypi.org/project/core-package/) for auth, RBAC,
+and the shared `User` model — **it never defines its own user/account
+model**; every record here is owned by a Core `User` via
+`settings.AUTH_USER_MODEL`. A user's *name* and *profile picture* live on
+Core's own `User` model (`first_name`/`last_name`/`avatar`), not here.
+
+Also depends on `blog-package` — this site's About/portfolio pages include a
+blog section, so installing `portfolio` installs `blog` too (see "Installing
+into a Core-based project" below).
+
+`Project.title`/`summary`/`description` and `Profile.headline`/`tagline`/
+`bio` are translatable via `apps.core.models.TranslatableModel` — a single
+`translations` JSON field per row (`{"fa": {"title": "...", ...}, "de":
+{...}}`), not a `title_en`/`title_fa` column per language. Add a language by
+calling `PUT /projects/{id}/translations/{language}` or
+`PUT /profile/me/translations/{language}`, no migration required.
+
+See Core's `AGENT.md` §10 ("Package architecture") for the full contract this
+package follows.
+
+## Installation
+
+```bash
+pip install portfolio-package
+```
+
+Requires Python 3.10+ and Django 5.2 (via core-package). This also installs
+`blog-package`.
+
+## Local development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e /path/to/Core/Core   # core-package, editable
+pip install -e ".[dev]"
+pytest
+```
+
+## Installing into a Core-based project
+
+1. Install it into the host repo's venv:
+   ```bash
+   pip install portfolio-package
+   ```
+   This also pulls in `blog-package`. You still need to do steps 2-4 for
+   **both** `portfolio` and `blog` — Core's "no auto-discovery, explicit
+   wiring" convention (§10) means the pip install is automatic, but
+   `INSTALLED_APPS`/router-mounting/`migrate` are not; see `blog`'s own
+   README for its exact `INSTALLED_APPS`/router lines. For local development
+   of either package, install it editable instead
+   (`pip install -e ../Packages/portfolio-package`).
+2. Add it to `INSTALLED_APPS` in the host's `config/settings/base.py`, under
+   the `# site packages` comment (after the local apps block):
+   ```python
+   # site packages
+   "blog",
+   "portfolio",
+   ```
+3. Mount its router in the host's `config/api.py`:
+   ```python
+   from blog.api import router as blog_router
+   from portfolio.api import router as portfolio_router
+   ...
+   api.add_router("/blog", blog_router)
+   api.add_router("/portfolio", portfolio_router)
+   ```
+   Since both are wildcard-free routers, order relative to the other
+   `add_router` calls doesn't matter.
+4. Migrate:
+   ```bash
+   python manage.py migrate
+   ```
+5. Optional — add a nav entry under `UNFOLD["SIDEBAR"]["navigation"]` in the
+   host's `config/settings/base.py` for its admin models (`Project`, `Profile`,
+   `Skill`, etc., and `blog`'s `Post`, `Comment`, etc.).
+
+## Endpoints
+
+Mounted at whatever prefix the host chooses (`/portfolio` in the example
+above):
+
+- `GET /projects` — paginated list of published projects (public), optional
+  `?user_id=` and `?lang=`
+- `GET /projects/by-slug/{slug}` — published project detail (public),
+  optional `?lang=`
+- `GET /profile?user_id=` — a user's About/hero content (public), optional
+  `?lang=`
+- `GET /skills`, `/services`, `/education`, `/certifications`,
+  `/social-links` — public read-only lists, optionally filtered by
+  `?user_id=`
+- `POST /projects`, `GET /projects/{project_id}`,
+  `PATCH /projects/{project_id}`, `DELETE /projects/{project_id}` —
+  admin-only (`require_role("admin")`, from Core)
+- `PUT /projects/{project_id}/translations/{language}` — admin-only; sets
+  the translated `title`/`summary`/`description` for that language
+- `PATCH /profile/me` — admin-only; create/update the caller's own `Profile`
+- `PUT /profile/me/translations/{language}` — admin-only; sets the
+  translated `headline`/`tagline`/`bio` for that language
+
+Skills/education/certifications/services/social-links/project images are
+managed through the Django admin (no write API for them yet —
+deliberately, to avoid building endpoints nothing needs yet).

portfolio_package-0.1.0/portfolio/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

portfolio_package-0.1.0/portfolio/admin.py

@@ -0,0 +1,82 @@
+from django.contrib import admin
+from unfold.admin import ModelAdmin, TabularInline
+
+from portfolio.models import (
+    Certification,
+    Education,
+    Experience,
+    Profile,
+    Project,
+    ProjectImage,
+    Service,
+    Skill,
+    SocialLink,
+    UserSkill,
+)
+
+
+class ProjectImageInline(TabularInline):
+    model = ProjectImage
+    extra = 1
+    fields = ("image", "caption", "order")
+
+
+@admin.register(Profile)
+class ProfileAdmin(ModelAdmin):
+    list_display = ("user", "headline", "years_experience", "clients_count", "projects_count")
+    search_fields = ("headline", "tagline", "bio")
+    readonly_fields = ("id", "created_at", "updated_at")
+
+
+@admin.register(Project)
+class ProjectAdmin(ModelAdmin):
+    list_display = ("title", "user", "is_published", "order", "created_at")
+    list_filter = ("is_published",)
+    search_fields = ("title", "slug", "summary")
+    prepopulated_fields = {"slug": ("title",)}
+    readonly_fields = ("id", "created_at", "updated_at")
+    filter_horizontal = ("services",)
+    inlines = [ProjectImageInline]
+
+
+@admin.register(Skill)
+class SkillAdmin(ModelAdmin):
+    list_display = ("name", "slug")
+    search_fields = ("name",)
+    prepopulated_fields = {"slug": ("name",)}
+
+
+@admin.register(UserSkill)
+class UserSkillAdmin(ModelAdmin):
+    list_display = ("user", "skill", "proficiency")
+    list_filter = ("skill",)
+
+
+@admin.register(SocialLink)
+class SocialLinkAdmin(ModelAdmin):
+    list_display = ("user", "platform", "url")
+    list_filter = ("platform",)
+
+
+@admin.register(Education)
+class EducationAdmin(ModelAdmin):
+    list_display = ("user", "institution", "degree", "start_date", "end_date")
+    search_fields = ("institution", "degree", "field_of_study")
+
+
+@admin.register(Experience)
+class ExperienceAdmin(ModelAdmin):
+    list_display = ("user", "title", "company", "start_date", "end_date")
+    search_fields = ("title", "company")
+
+
+@admin.register(Certification)
+class CertificationAdmin(ModelAdmin):
+    list_display = ("user", "title", "issuer", "issue_date")
+    search_fields = ("title", "issuer")
+
+
+@admin.register(Service)
+class ServiceAdmin(ModelAdmin):
+    list_display = ("title", "user", "order")
+    prepopulated_fields = {"slug": ("title",)}

portfolio_package-0.1.0/portfolio/api.py

@@ -0,0 +1,164 @@
+import uuid
+
+from apps.core.pagination import PageParams, paginate_queryset
+from apps.core.permissions import require_role
+from apps.core.schemas import PagedResponse
+from ninja import Router, Status
+
+from portfolio import services
+from portfolio.models import Certification, Education, Experience, Service, Skill, SocialLink, UserSkill
+from portfolio.schemas import (
+    CertificationOut,
+    EducationOut,
+    ExperienceOut,
+    ProfileOut,
+    ProfileTranslationIn,
+    ProfileUpdateIn,
+    ProjectIn,
+    ProjectOut,
+    ProjectTranslationIn,
+    ProjectUpdateIn,
+    ServiceOut,
+    SkillOut,
+    SocialLinkOut,
+)
+
+router = Router(tags=["portfolio"])
+
+# NOTE: the public detail lookup lives at "/projects/by-slug/{slug}" (two
+# segments) rather than "/projects/{slug}", specifically to avoid sharing a
+# URL shape with the admin "/projects/{project_id}" route below. Two
+# differently-named wildcards at the same single-segment position
+# ("/projects/{slug}" vs "/projects/{project_id}") would compile to
+# identical regexes but be registered as separate Django urlpatterns bound to
+# disjoint HTTP methods (GET-only vs PATCH/DELETE-only) — whichever is
+# registered first "wins" the match for every method, and Django returns 405
+# for the other route's methods rather than trying the next pattern. See
+# Core's AGENT.md §9 point 5 for the same class of bug. Giving the public
+# lookup a distinct path shape sidesteps it entirely rather than relying on
+# registration order.
+
+# --- Public read endpoints --------------------------------------------------
+
+
+@router.get("/projects", response=PagedResponse[ProjectOut], auth=None)
+async def list_projects(request, page: PageParams = PageParams(), user_id: uuid.UUID | None = None, lang: str | None = None):  # noqa: B008 (ninja query-schema idiom)
+    items, meta = await paginate_queryset(services.published_project_queryset(user_id), page)
+    return {"items": services.serialize_projects(items, lang), "meta": meta}
+
+
+@router.get("/projects/by-slug/{slug}", response=ProjectOut, auth=None)
+async def get_project_by_slug(request, slug: str, lang: str | None = None):
+    project = await services.get_published_project_or_404(slug)
+    return services.serialize_projects([project], lang)[0]
+
+
+@router.get("/profile", response=ProfileOut, auth=None)
+async def get_profile(request, user_id: uuid.UUID, lang: str | None = None):
+    return await services.get_profile_or_404(user_id, lang)
+
+
+@router.get("/skills", response=list[SkillOut], auth=None)
+async def list_skills(request, user_id: uuid.UUID | None = None):
+    """Without `user_id`: the global skill catalog. With it: that owner's
+    skills (`UserSkill`) with their proficiency, highest first."""
+    if user_id is None:
+        return [s async for s in Skill.objects.all()]
+    qs = UserSkill.objects.filter(user_id=user_id).select_related("skill").order_by("-proficiency", "skill__name")
+    return [
+        {"id": us.skill.id, "name": us.skill.name, "slug": us.skill.slug, "proficiency": us.proficiency}
+        async for us in qs
+    ]
+
+
+@router.get("/services", response=list[ServiceOut], auth=None)
+async def list_services(request, user_id: uuid.UUID | None = None):
+    qs = Service.objects.all()
+    if user_id is not None:
+        qs = qs.filter(user_id=user_id)
+    return [s async for s in qs]
+
+
+@router.get("/education", response=list[EducationOut], auth=None)
+async def list_education(request, user_id: uuid.UUID | None = None):
+    qs = Education.objects.all()
+    if user_id is not None:
+        qs = qs.filter(user_id=user_id)
+    return [e async for e in qs]
+
+
+@router.get("/experience", response=list[ExperienceOut], auth=None)
+async def list_experience(request, user_id: uuid.UUID | None = None):
+    qs = Experience.objects.all()
+    if user_id is not None:
+        qs = qs.filter(user_id=user_id)
+    return [e async for e in qs]
+
+
+@router.get("/certifications", response=list[CertificationOut], auth=None)
+async def list_certifications(request, user_id: uuid.UUID | None = None):
+    qs = Certification.objects.all()
+    if user_id is not None:
+        qs = qs.filter(user_id=user_id)
+    return [c async for c in qs]
+
+
+@router.get("/social-links", response=list[SocialLinkOut], auth=None)
+async def list_social_links(request, user_id: uuid.UUID | None = None):
+    qs = SocialLink.objects.all()
+    if user_id is not None:
+        qs = qs.filter(user_id=user_id)
+    return [s async for s in qs]
+
+
+# --- Admin-only write endpoints (Project) -----------------------------------
+
+
+@router.post("/projects", response={201: ProjectOut})
+@require_role("admin")
+async def create_project(request, payload: ProjectIn):
+    project = await services.create_project(request.auth, request.auth.id, **payload.model_dump())
+    return Status(201, services.serialize_projects([project])[0])
+
+
+@router.get("/projects/{project_id}", response=ProjectOut)
+@require_role("admin")
+async def get_project(request, project_id: uuid.UUID):
+    project = await services.get_project_or_404(project_id)
+    return services.serialize_projects([project])[0]
+
+
+@router.patch("/projects/{project_id}", response=ProjectOut)
+@require_role("admin")
+async def update_project(request, project_id: uuid.UUID, payload: ProjectUpdateIn):
+    project = await services.update_project(request.auth, project_id, **payload.model_dump())
+    return services.serialize_projects([project])[0]
+
+
+@router.delete("/projects/{project_id}", response={204: None})
+@require_role("admin")
+async def delete_project(request, project_id: uuid.UUID):
+    await services.delete_project(request.auth, project_id)
+    return Status(204, None)
+
+
+@router.put("/projects/{project_id}/translations/{language}", response=ProjectOut)
+@require_role("admin")
+async def set_project_translation(request, project_id: uuid.UUID, language: str, payload: ProjectTranslationIn):
+    project = await services.set_project_translation(request.auth, project_id, language, **payload.model_dump())
+    return services.serialize_projects([project], language)[0]
+
+
+# --- Own profile (About/hero content) ----------------------------------------
+
+
+@router.patch("/profile/me", response=ProfileOut)
+@require_role("admin")
+async def update_my_profile(request, payload: ProfileUpdateIn):
+    return await services.update_own_profile(request.auth, **payload.model_dump())
+
+
+@router.put("/profile/me/translations/{language}", response=ProfileOut)
+@require_role("admin")
+async def set_my_profile_translation(request, language: str, payload: ProfileTranslationIn):
+    return await services.set_profile_translation(request.auth, language, **payload.model_dump())

portfolio_package-0.1.0/portfolio/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class PortfolioConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "portfolio"
+    label = "portfolio"
+    verbose_name = "Portfolio"