ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enforce plugin contract purity: single import surface via shopdb.api

Browse Source 
Plugins were reaching into internal core paths (shopdb.core.models.*,
shopdb.extensions, shopdb.utils.*), coupling them to core's file layout and
violating the ADR-001 contract. Consolidate onto one versioned surface.

- shopdb.api: expand from 2 helpers to the full plugin import surface -
  db, cache; BaseModel, AuditMixin; core models (Asset, AssetType,
  AssetStatus, Vendor, Model, Communication, CommunicationType, Location,
  Setting, AuditLog, Application, AppVersion, OperatingSystem); response +
  pagination helpers; employee_connection. Documented in PLUGIN-HOOKS.md.
- Migrate all 22 plugin source files to import only from shopdb.api (plus
  shopdb.plugins.base for the ABC).
- Drop the printers plugin's legacy MachineType dependency: remove
  _ensure_legacy_machine_types and the seed_supplies machinetypeid lookup
  (Model.machinetypeid is nullable; printers carry type via PrinterType).
- Guard test test_plugins_only_import_contract_surface scans plugin source
  and fails on any core import outside shopdb.api / shopdb.plugins.base.
- Scaffold templates updated so generated plugins are contract-pure.
- Bump __contract_version__ 0.2.0 -> 0.3.0 (additive surface expansion;
  manifests pin <1.0.0 so they still satisfy).

145 tests pass, naming/style green, app factory boots all 6 plugins.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
cproudlock
2026-06-26 16:45:06 -04:00
parent 37ffb4add5
commit f663cc5bbe
29 changed files with 2152 additions and 2107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
plugins/printers/api/asset_routes.py
View File

@@ -5,15 +5,7 @@ import logging
from flask import Blueprint, request
from flask_jwt_extended import jwt_required
from shopdb.extensions import db, cache
from shopdb.core.models import Asset, AssetType, Vendor, Model, Communication, CommunicationType
from shopdb.utils.responses import (
success_response,
error_response,
paginated_response,
ErrorCodes
)
from shopdb.utils.pagination import get_pagination_params, paginate_query
from shopdb.api import db, cache, Asset, AssetType, Vendor, Model, Communication, CommunicationType, success_response, error_response, paginated_response, ErrorCodes, get_pagination_params, paginate_query
from ..models import Printer, PrinterType, ModelSupply
from ..models.model_supply import SUPPLY_TYPES, SUPPLY_COLORS, CAPACITY_TIERS
@@ -565,7 +557,7 @@ def _get_low_supplies_data():
# location name for the report row
location_name = None
if asset.locationid:
from shopdb.core.models import Location
from shopdb.api import Location
loc = Location.query.get(asset.locationid)
if loc:
location_name = loc.locationname

3
plugins/printers/models/model_supply.py
View File

@@ -6,8 +6,7 @@ drum/waste/maintenance item). Lets new models and their toners be added
through the API/UI without a code change.
"""
from shopdb.extensions import db
from shopdb.core.models.base import BaseModel
from shopdb.api import db, BaseModel
# allowed values, surfaced to the UI via the /supplies/meta endpoint

243
plugins/printers/models/printer.py
View File

@@ -1,122 +1,121 @@
"""Printer plugin models - new Asset-based architecture."""
from shopdb.extensions import db
from shopdb.core.models.base import BaseModel
class PrinterType(BaseModel):
"""
Printer type classification.
Examples: Laser, Inkjet, Label, MFP, Plotter, etc.
"""
__tablename__ = 'printertypes'
printertypeid = db.Column(db.Integer, primary_key=True)
printertype = db.Column(db.String(100), unique=True, nullable=False)
description = db.Column(db.Text)
icon = db.Column(db.String(50), comment='Icon name for UI')
def __repr__(self):
return f"<PrinterType {self.printertype}>"
class Printer(BaseModel):
"""
Printer-specific extension data (new Asset architecture).
Links to core Asset table via assetid.
Stores printer-specific fields like type, Windows name, share name, etc.
"""
__tablename__ = 'printers'
printerid = db.Column(db.Integer, primary_key=True)
# Link to core asset
assetid = db.Column(
db.Integer,
db.ForeignKey('assets.assetid', ondelete='CASCADE'),
unique=True,
nullable=False,
index=True
)
# Printer classification
printertypeid = db.Column(
db.Integer,
db.ForeignKey('printertypes.printertypeid'),
nullable=True
)
# Vendor
vendorid = db.Column(
db.Integer,
db.ForeignKey('vendors.vendorid'),
nullable=True
)
modelnumberid = db.Column(
db.Integer,
db.ForeignKey('models.modelnumberid'),
nullable=True
)
# Network identity
hostname = db.Column(
db.String(100),
index=True,
comment='Network hostname'
)
# Windows/Network naming
windowsname = db.Column(
db.String(255),
comment='Windows printer name (e.g., \\\\server\\printer)'
)
sharename = db.Column(
db.String(100),
comment='CSF/share name'
)
# Installation
iscsf = db.Column(db.Boolean, default=False, comment='Is CSF printer')
installpath = db.Column(db.String(255), comment='Driver install path')
# Printer PIN (for secure print)
pin = db.Column(db.String(20))
# Features
iscolor = db.Column(db.Boolean, default=False, comment='Color capable')
isduplex = db.Column(db.Boolean, default=False, comment='Duplex capable')
isnetwork = db.Column(db.Boolean, default=True, comment='Network connected')
# Relationships
asset = db.relationship(
'Asset',
backref=db.backref('printer', uselist=False, lazy='joined')
)
printertype = db.relationship('PrinterType', backref='printers')
vendor = db.relationship('Vendor', backref='printer_items')
model = db.relationship('Model', backref='printer_items')
__table_args__ = (
db.Index('idx_printer_type', 'printertypeid'),
db.Index('idx_printer_hostname', 'hostname'),
db.Index('idx_printer_windowsname', 'windowsname'),
)
def __repr__(self):
return f"<Printer {self.hostname or self.assetid}>"
def to_dict(self):
"""Convert to dictionary with related names."""
result = super().to_dict()
# Add related object names
if self.printertype:
result['printertypename'] = self.printertype.printertype
if self.vendor:
result['vendorname'] = self.vendor.vendor
if self.model:
result['modelname'] = self.model.modelnumber
return result
"""Printer plugin models - new Asset-based architecture."""
from shopdb.api import db, BaseModel
class PrinterType(BaseModel):
"""
Printer type classification.
Examples: Laser, Inkjet, Label, MFP, Plotter, etc.
"""
__tablename__ = 'printertypes'
printertypeid = db.Column(db.Integer, primary_key=True)
printertype = db.Column(db.String(100), unique=True, nullable=False)
description = db.Column(db.Text)
icon = db.Column(db.String(50), comment='Icon name for UI')
def __repr__(self):
return f"<PrinterType {self.printertype}>"
class Printer(BaseModel):
"""
Printer-specific extension data (new Asset architecture).
Links to core Asset table via assetid.
Stores printer-specific fields like type, Windows name, share name, etc.
"""
__tablename__ = 'printers'
printerid = db.Column(db.Integer, primary_key=True)
# Link to core asset
assetid = db.Column(
db.Integer,
db.ForeignKey('assets.assetid', ondelete='CASCADE'),
unique=True,
nullable=False,
index=True
)
# Printer classification
printertypeid = db.Column(
db.Integer,
db.ForeignKey('printertypes.printertypeid'),
nullable=True
)
# Vendor
vendorid = db.Column(
db.Integer,
db.ForeignKey('vendors.vendorid'),
nullable=True
)
modelnumberid = db.Column(
db.Integer,
db.ForeignKey('models.modelnumberid'),
nullable=True
)
# Network identity
hostname = db.Column(
db.String(100),
index=True,
comment='Network hostname'
)
# Windows/Network naming
windowsname = db.Column(
db.String(255),
comment='Windows printer name (e.g., \\\\server\\printer)'
)
sharename = db.Column(
db.String(100),
comment='CSF/share name'
)
# Installation
iscsf = db.Column(db.Boolean, default=False, comment='Is CSF printer')
installpath = db.Column(db.String(255), comment='Driver install path')
# Printer PIN (for secure print)
pin = db.Column(db.String(20))
# Features
iscolor = db.Column(db.Boolean, default=False, comment='Color capable')
isduplex = db.Column(db.Boolean, default=False, comment='Duplex capable')
isnetwork = db.Column(db.Boolean, default=True, comment='Network connected')
# Relationships
asset = db.relationship(
'Asset',
backref=db.backref('printer', uselist=False, lazy='joined')
)
printertype = db.relationship('PrinterType', backref='printers')
vendor = db.relationship('Vendor', backref='printer_items')
model = db.relationship('Model', backref='printer_items')
__table_args__ = (
db.Index('idx_printer_type', 'printertypeid'),
db.Index('idx_printer_hostname', 'hostname'),
db.Index('idx_printer_windowsname', 'windowsname'),
)
def __repr__(self):
return f"<Printer {self.hostname or self.assetid}>"
def to_dict(self):
"""Convert to dictionary with related names."""
result = super().to_dict()
# Add related object names
if self.printertype:
result['printertypename'] = self.printertype.printertype
if self.vendor:
result['vendorname'] = self.vendor.vendor
if self.model:
result['modelname'] = self.model.modelnumber
return result

29
plugins/printers/plugin.py
View File

@@ -9,9 +9,7 @@ from flask import Flask, Blueprint
import click
from shopdb.plugins.base import BasePlugin, PluginMeta
from shopdb.extensions import db
from shopdb.core.models.machine import MachineType
from shopdb.core.models import AssetType
from shopdb.api import db, AssetType
from .models import Printer, PrinterType, ModelSupply
from .api import printers_asset_bp
@@ -104,7 +102,6 @@ class PrintersPlugin(BasePlugin):
with app.app_context():
self._ensure_asset_type()
self._ensure_printer_types()
self._ensure_legacy_machine_types()
logger.info("Printers plugin installed")
def _ensure_asset_type(self) -> None:
@@ -149,30 +146,6 @@ class PrintersPlugin(BasePlugin):
db.session.commit()
def _ensure_legacy_machine_types(self) -> None:
"""Ensure basic printer machine types exist (legacy architecture)."""
printertypes = [
('Laser Printer', 'Printer', 'Standard laser printer'),
('Inkjet Printer', 'Printer', 'Inkjet printer'),
('Label Printer', 'Printer', 'Label/barcode printer'),
('Multifunction Printer', 'Printer', 'MFP with scan/copy/fax'),
('Plotter', 'Printer', 'Large format plotter'),
]
for name, category, description in printertypes:
existing = MachineType.query.filter_by(machinetype=name).first()
if not existing:
mt = MachineType(
machinetype=name,
category=category,
description=description,
icon='printer'
)
db.session.add(mt)
logger.debug(f"Created machine type: {name}")
db.session.commit()
def on_uninstall(self, app: Flask) -> None:
"""Called when plugin is uninstalled."""
logger.info("Printers plugin uninstalled")

10
plugins/printers/services/seed_supplies.py
View File

@@ -19,9 +19,7 @@ Key facts encoded here:
import logging
from shopdb.extensions import db
from shopdb.core.models import Vendor, Model
from shopdb.core.models.machine import MachineType
from shopdb.api import db, Vendor, Model
from ..models import ModelSupply
@@ -311,9 +309,6 @@ def seedsupplies():
model that matches a family's keys; if a family matches no existing model,
creates a canonical model row so its toners are still available.
"""
printertype = MachineType.query.filter_by(category='Printer').first()
printertypeid = printertype.machinetypeid if printertype else None
models_touched = 0
supplies_added = 0
@@ -322,10 +317,11 @@ def seedsupplies():
targets = _matching_models(family['matchkeys'], vendor.vendorid)
if not targets:
# machinetypeid is a legacy Model column (nullable); printers are
# asset-based now and carry their type via PrinterType, not here.
model = Model(
modelnumber=family['canonical'],
vendorid=vendor.vendorid,
machinetypeid=printertypeid,
)
db.session.add(model)
db.session.flush()

6
plugins/printers/services/zabbix_service.py
View File

@@ -24,7 +24,7 @@ from typing import Dict, List, Optional
import requests
from flask import current_app
from shopdb.extensions import cache
from shopdb.api import cache
logger = logging.getLogger(__name__)
@@ -55,7 +55,7 @@ class ZabbixService:
@property
def isenabled(self) -> bool:
"""Whether the integration is switched on."""
from shopdb.core.models import Setting
from shopdb.api import Setting
db_enabled = Setting.get('zabbix_enabled')
if db_enabled is not None:
return bool(db_enabled)
@@ -66,7 +66,7 @@ class ZabbixService:
"""Enabled, and a URL plus token are present."""
if not self.isenabled:
return False
from shopdb.core.models import Setting
from shopdb.api import Setting
self._url = Setting.get('zabbix_url') or current_app.config.get('ZABBIX_URL')
self._token = Setting.get('zabbix_token') or current_app.config.get('ZABBIX_TOKEN')
return bool(self._url and self._token)