<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Ricardo García Ramírez on Medium]]></title>
        <description><![CDATA[Stories by Ricardo García Ramírez on Medium]]></description>
        <link>https://medium.com/@ricardogr07?source=rss-93688570991c------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*2JVuW2M1ZYA_VZUNizD4HQ.png</url>
            <title>Stories by Ricardo García Ramírez on Medium</title>
            <link>https://medium.com/@ricardogr07?source=rss-93688570991c------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 12:16:50 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@ricardogr07/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[You’re Adding AI to the Wrong Layer!]]></title>
            <link>https://levelup.gitconnected.com/youre-adding-ai-to-the-wrong-layer-be0e6aa51197?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/be0e6aa51197</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[coding-style]]></category>
            <category><![CDATA[coding-standards]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[clean-code]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Wed, 05 Aug 2026 19:11:03 GMT</pubDate>
            <atom:updated>2026-08-05T19:11:03.578Z</atom:updated>
            <content:encoded><![CDATA[<p><em>The same discipline that killed raw SQL in route handlers needs to kill scattered AI calls in your domain layer.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EntZCyZqwrQah4gyskKMkQ.png" /></figure><p>An engineer on my team asked a reasonable question last month: “Can we write a unit test for this checkout enrichment function?”</p><p>I hesitated. The function works fine. It’s been used for some time now. It calls the OpenAI API to generate a short product description summary on new items automatically, and it works <em>okish, (I mean do we REALLY need AI for this, probably not)</em>. But testing it means either mocking HTTP at the transport layer, spinning up a VCR-style cassette, or paying for tokens on every CI run. None of those are good answers. I didn’t have a clean one.</p><p>That same week, someone noticed that anthropic.messages.create() appears in our checkout service. Nobody could explain why the checkout service knows anything about Anthropic’s SDK. And our retry-on-rate-limit logic exists in at least four places now, each slightly different, each written by a different engineer at a different speed (or by some random LLM that added it).</p><p>The AI works (kinda, I mean, we’re being pushed to include it). The architecture doesn’t.</p><p>By the end of this article, you’ll be able to identify whether your codebase has this problem, understand why it compounds, and apply the fix. I won’t say don’t use AI because it’s here to stay, but rather how can we use it effectively without killing our codebase and bill.</p><h3>You’ve Seen This Before</h3><p>The year is 2015. You open a .NET codebase and find raw SQL in the controller action. Not just one, but twelve. Each is slightly different. One handles NULL differently than the others. The retry logic on a database timeout is a copy-paste job with a typo in the catch block.</p><p>You know exactly how this happened. The feature needed to ship. The SQL worked. Moving fast looked like this.</p><p>And you know exactly how it ended: a three-week “database abstraction” project, a bug introduced during migration, a postmortem, and a new rule on the team wiki.</p><p>The industry eventually learned that database access is an I/O boundary. You don’t scatter it through domain logic. You put it behind a repository. You mock the repository in tests. Your business logic stays testable and portable.</p><p>In 2026, we repeated the mistake. We just changed the noun.</p><h3>The Three Symptoms</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lK6IKkgqp3npyqvWDI9nTA.png" /></figure><p>If you’re not sure whether your team did this, here are the tells:</p><ol><li>You can’t unit-test a function that calls an LLM without mocking the SDK.</li></ol><pre># This is in your domain service. It does not belong here.<br>def enrich_product(product: Product) -&gt; Product:<br>    response = openai_client.chat.completions.create(<br>        model=&quot;gpt-4o&quot;,<br>        messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: f&quot;Summarize: {product.description}&quot;}]<br>    )<br>    product.summary = response.choices[0].message.content<br>    return product</pre><p>To test enrich_product, you need a live API key or a unittest.mock.patch on the OpenAI client. Neither is acceptable for a domain function. The function isn’t doing anything wrong, hence it’s <em>in the wrong place</em>. Also, why do you need to enrich it this way? Not sure about why people just make these random calls everywhere, but anyways.</p><p>2. Your retry logic is duplicated.</p><pre># In payments/service.py<br>for attempt in range(3):<br>    try:<br>        result = client.chat.completions.create(...)<br>        break<br>    except RateLimitError:<br>        time.sleep(2 ** attempt)<br><br># In catalog/enrichment.py<br>for attempt in range(5):  # 5 here, 3 there — why?<br>    try:<br>        result = anthropic.messages.create(...)<br>        break<br>    except APIStatusError:<br>        time.sleep(attempt)  # Linear, not exponential — different bug</pre><p>Two retry implementations. Two different retry counts. Two different backoff strategies. One of them has a bug. You know it. You just don’t know which one.</p><p>3. Switching models or providers means touching a lot of files.</p><p>Someone proposes moving from GPT-4o to Claude Sonnet because the cost is 80% lower for your use case. The response from your senior engineer: “That’s going to touch a lot of files.”</p><p>Translation: the provider SDK is imported and called directly in a dozen places. In codebases I’ve seen, that typically means 15–50 files. The switch is not a configuration change; it’s a full refactor. And oh boy, are those expensive in dev time.</p><p>That response tells you everything about your architecture. Or the lack of one.</p><h3>The Mental Model That’s Missing</h3><p>LLM calls are external I/O. Not utilities. Not helpers. I/O.</p><p>Same latency profile as a database call. Same failure modes (network, rate limits, timeouts). Same cost model (you pay per call, just like database connections have overhead). Same testability concern (you don’t want real calls in unit tests).</p><p>The reason we don’t scatter database calls through domain logic isn’t aesthetic. It’s because coupling to an external I/O boundary at the wrong layer makes the system brittle, untestable, and expensive to change. Every argument that applies to SQL applies to openai.chat.completions.create().</p><p>Unlike a database, an LLM’s response format is probabilistic; it can drift across model versions. Output validation (Pydantic schemas, structured output APIs) is another responsibility your abstraction layer handles cleanly in one place, which only strengthens the case for the boundary.</p><p>The mistake isn’t using AI, I know I know it’s here to stay and it makes us a 100x engineer with a 3-weekend project that will make you millions, and you can retire from your SDE job, allegedly. The mistake is treating it like a utility function, because it’s not (and it’s expensive!).</p><h3>The Fix (It’s Not Complicated)</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3w7hFPNzRKpIsWpDpiIUuA.png" /></figure><p>One abstraction. One real implementation per provider. One fake for tests.</p><pre>from abc import ABC, abstractmethod<br><br>class AIService(ABC):<br>    @abstractmethod<br>    def complete(self, messages: list[dict]) -&gt; str: ...<br><br>    def ask(self, prompt: str) -&gt; str:<br>        return self.complete([{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: prompt}])<br><br>class OpenAIService(AIService):<br>    def __init__(self, client: OpenAI, model: str = &quot;gpt-4o-mini&quot;):<br>        self._client = client<br>        self._model = model<br><br>    def complete(self, messages: list[dict]) -&gt; str:<br>        response = self._client.chat.completions.create(<br>            model=self._model,<br>            messages=messages,<br>        )<br>        return response.choices[0].message.content<br><br>class FakeAIService(AIService):<br>    def __init__(self, response: str = &quot;fake response&quot;):<br>        self._response = response<br><br>    def complete(self, messages: list[dict]) -&gt; str:<br>        return self._response</pre><p>Now your domain logic looks like this:</p><pre>def enrich_product(product: Product, ai: AIService) -&gt; Product:<br>    product.summary = ai.ask(f&quot;Summarize in one sentence: {product.description}&quot;)<br>    return product</pre><p>Unit test with FakeAIService. Integration test with OpenAIService. Switch to Anthropic by writing AnthropicService(AIService) and changing one wire in your DI container. Retry logic lives in one place, in OpenAIService.complete, not scattered across twelve call sites.</p><p>A note on the interface: complete(messages) takes the same shape as the actual OpenAI and Anthropic SDK: a list of message dicts. This matters: system prompts, few-shot examples, and multi-turn conversations all work naturally because the shape is already right. The ask(prompt) convenience method handles the common single-turn case without boilerplate. For tool calls and structured output, the abstraction needs to grow and it grows in one place, not across every call site scattered through your domain.</p><p>Everything else becomes boring. That’s the goal. Boring is good; good engineering is kind of boring and follows basic principles. That’s why the whole enterprise old Java architecture from the legacy code, which nobody has touched in 15 years, is still up and running. Make it boring, repeatable, and testable.</p><h3>“But We Needed to Ship”</h3><p>I know. I’ve been there and still am. The product manager wanted a demo by Friday. The abstraction felt like ceremony when the feature wasn’t even validated yet. You made a pragmatic call.</p><p>Here’s the honest accounting of that call: the two-week AI feature that shipped without the abstraction is now costing you in every sprint. Every new AI feature adds another raw callsite. Every junior engineer models the pattern they see. The retry bug that lives in the catalog but not payments is a silent correctness issue. The “what if we switch providers?” question gets more expensive to answer every quarter.</p><p>Moving fast with the wrong architecture isn’t fast. It’s a loan. The interest is paid in every subsequent sprint that touches anything AI-adjacent.</p><h3>What to Do This Week</h3><ul><li>If your LLM SDK is imported directly in domain code, it&#39;s in the wrong layer. Create an AIService protocol or abstract class.</li><li>If you have retry logic in more than one place, it belongs in the implementation class, not at the call site.</li><li>If switching providers would require touching more than one file, your abstraction boundary is missing.</li><li>If you can’t unit test a function without mocking the OpenAI SDK, the function is coupled to the wrong thing.</li><li>If your tests skip AI-touching code entirely, that code has no meaningful test coverage, the abstraction gives you that coverage back.</li><li>The refactor doesn’t have to be a project: extract one callsite per week. The codebase improves incrementally; you don’t need a big-bang rewrite.</li></ul><h3>The Tax Is Real</h3><p>I’m not describing a hypothetical architectural nicety. I’m describing a pattern I’ve watched teams build and pay for, including myself in personal projects.</p><p>The engineers who scattered those first LLM calls weren’t careless, they were moving fast on something new and exciting, making the same tradeoff engineers have made for forty years when something new arrived and the rules felt like they might not apply this time.</p><p>The rules apply. External I/O belongs at the boundary. Abstractions exist so domain logic stays testable and portable. None of that changed because the I/O is a language model instead of a database.</p><p>You already solved this problem once. You called it the repository pattern.</p><p>Now you get to solve it again. The pattern is the same. The noun is different.</p><p>The question is whether you start this quarter or next quarter. The refactor tax keeps compounding either way.</p><p>If you found this post helpful, don’t forget to <strong>👏 clap</strong> to show your support!</p><p>I’d also love to hear your thoughts and insights on the techniques covered in this article. 💡 Feel free to share your experiences in the <strong>comments</strong> 💬.</p><figure><a href="https://medium.com/@rgr5882/subscribe"><img alt="" src="https://cdn-images-1.medium.com/max/780/1*HaafLJIgmLZMblLS4wtE3w.png" /></a></figure><h3>Connect with Me on LinkedIn!</h3><p>You can also connect with me on <a href="https://www.linkedin.com/in/ricardogarciaramirez/"><strong>LinkedIn</strong> </a>for updates on my latest posts and projects. 🌐 Let’s keep the conversation going!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=be0e6aa51197" width="1" height="1" alt=""><hr><p><a href="https://levelup.gitconnected.com/youre-adding-ai-to-the-wrong-layer-be0e6aa51197">You’re Adding AI to the Wrong Layer!</a> was originally published in <a href="https://levelup.gitconnected.com/">Level Up Coding</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[When try/finally Becomes a Code Smell (And the Fix)]]></title>
            <link>https://blog.devgenius.io/when-try-finally-becomes-a-code-smell-and-the-fix-d4bbe9c9ac99?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/d4bbe9c9ac99</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[clean-code]]></category>
            <category><![CDATA[code-smells]]></category>
            <category><![CDATA[coding-best-practices]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Sun, 19 Jul 2026 19:46:01 GMT</pubDate>
            <atom:updated>2026-07-19T19:46:01.663Z</atom:updated>
            <content:encoded><![CDATA[<p>The __enter__/__exit__ protocol generalizes to every acquire/release lifecycle, not just file handles.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*v4Zk_cYcA6I69ONhfAy9Zg.png" /></figure><p>You open a database connection, run a query, and close it in a finally block. You’ve done it a hundred times. Then you add retry logic, and the try/finally grows. Then you nest another resource inside it. By the time someone reviews the PR, there are three nesting levels of try/finally, and the indentation alone is a warning sign.</p><p>The tragedy: Python already has a protocol for exactly this. The same mechanism that closes your files can manage your connections, release your locks, tear down your test patches, and clean up your temp directories, and it composes cleanly when you need more than one resource at a time.</p><p>You just haven’t extended the pattern you already know.</p><p>By the end of this article, you’ll have three reusable patterns: @contextmanager, class-based __enter__/__exit__, and ExitStack, that eliminate defensive try/finally blocks from your resource management code, plus the exception-handling gotcha that bites every implementer once.</p><h4>The try/finally Smell</h4><p>Here’s a realistic database connection before the refactor (using sqlite3, which is stdlib and requires no setup):</p><pre>import sqlite3<br><br>def get_user(user_id: int) -&gt; tuple:<br>    conn = sqlite3.connect(&quot;mydb.db&quot;)<br>    try:<br>        cursor = conn.cursor()<br>        try:<br>            cursor.execute(&quot;SELECT * FROM users WHERE id = ?&quot;, (user_id,))<br>            return cursor.fetchone()<br>        finally:<br>            cursor.close()<br>    except Exception:<br>        conn.rollback()<br>        raise<br>    finally:<br>        conn.close()</pre><p>This is not wrong. It is correct. The problem is that it reads like defensive trench-digging: every resource gets its own try/finally fortress, and they nest. Add a third resource and the indentation reaches halfway across the screen. The issue is not the logic. The issue is that the <em>pattern</em> has no name, no composability, and no way to reuse it across callsites. That is the smell: not incorrectness, but the friction of reinventing the same teardown structure every time.</p><h4>The Protocol in One Minute</h4><p>Python’s with statement calls two methods on an object:</p><ul><li>__enter__(self): called when entering the with block; its return value is bound to the as variable.</li><li>__exit__(self, exc_type, exc_val, exc_tb): called when leaving the block, whether normally or via exception.</li></ul><pre>with some_resource() as r:<br>    r.do_something()<br># __exit__ always runs here, even if do_something() raised</pre><p>That’s the entire protocol. open() implements it. threading.Lock implements it. unittest.mock.patch implements it. Any object with these two methods works as a context manager.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HuPedmR6UeLiCKeuIW288g.png" /></figure><h4>@contextmanager: The Fast Path (80% of Cases)</h4><p>contextlib.contextmanager lets you write a context manager as a generator function. Everything before the yield is __enter__. Everything after is __exit__. Wrap it in try/finally to guarantee cleanup. If you omit try/finally, the cleanup code after yield never runs when an exception is raised inside the with block.</p><pre>from contextlib import contextmanager<br>import sqlite3<br><br>@contextmanager<br>def db_connection(path: str):<br>    # swap sqlite3.connect for psycopg2.connect(dsn=path) to use Postgres<br>    conn = sqlite3.connect(path)<br>    try:<br>        yield conn          # this is what the `as` variable receives<br>        conn.commit()<br>    except Exception:<br>        conn.rollback()<br>        raise<br>    finally:<br>        conn.close()<br><br># Usage<br>with db_connection(&quot;mydb.db&quot;) as conn:<br>    cursor = conn.cursor()<br>    cursor.execute(&quot;SELECT * FROM users WHERE id = ?&quot;, (42,))<br>    print(cursor.fetchone())</pre><p>Before: three levels of nesting, teardown scattered across try, except, and finally. After: the commit/rollback logic lives in one place, and the with call at the use site is a single line. If an exception escapes the with block, the generator’s except catches it, rolls back, re-raises, and the finally closes the connection regardless.</p><p>Rule of thumb: if your context manager has no state between uses, reach for @contextmanager first.</p><h4>When to Write __enter__/__exit__ Instead</h4><p>The decorator form gets awkward when you need:</p><ul><li>State shared across calls: e.g., a connection pool that tracks how many connections are open.</li><li>Reuse as a base class: subclasses can override __enter__ or __exit__ cleanly.</li><li>__init__ parameters stored as instance variables: though this works fine with a closure too.</li></ul><p>Here’s a stateful timer context manager that records elapsed time:</p><pre>import time<br><br>class Timer:<br>    def __init__(self, name: str = &quot;&quot;):<br>        self.name = name<br>        self.elapsed: float = 0.0<br><br>    def __enter__(self) -&gt; &quot;Timer&quot;:<br>        self._start = time.perf_counter()<br>        return self          # `as` variable points to self<br><br>    def __exit__(self, exc_type, exc_val, exc_tb) -&gt; bool:<br>        self.elapsed = time.perf_counter() - self._start<br>        if self.name:<br>            print(f&quot;{self.name}: {self.elapsed:.4f}s&quot;)<br>        return False         # don&#39;t suppress exceptions<br><br># Usage<br>with Timer(&quot;db query&quot;) as t:<br>    time.sleep(0.1)          # simulate work<br><br>print(f&quot;Captured: {t.elapsed:.4f}s&quot;)</pre><p>The Timer instance survives the with block, so you can inspect t.elapsed afterward. A generator-based approach would need a mutable container or closure to expose that state. The class form keeps it on self, which is the natural place.</p><h3>Real Patterns: Beyond the File</h3><h4>Thread Lock</h4><p>threading.Lock already implements the protocol. Just use it:</p><pre>import threading<br><br>_lock = threading.Lock()<br>_shared: list = []<br><br>def safe_append(item):<br>    with _lock:<br>        _shared.append(item)</pre><h4>Temporary Directory</h4><pre>from contextlib import contextmanager<br>import tempfile, shutil, pathlib<br><br>@contextmanager<br>def temp_dir():<br>    path = pathlib.Path(tempfile.mkdtemp())<br>    try:<br>        yield path<br>    finally:<br>        shutil.rmtree(path, ignore_errors=True)<br><br>with temp_dir() as d:<br>    (d / &quot;scratch.txt&quot;).write_text(&quot;working...&quot;)<br>    print(d)<br>    # directory and all contents deleted on exit<br><br># Output:<br># /tmp/tmpXXXXXX (path varies)</pre><p>The stdlib also ships tempfile.TemporaryDirectory() which does exactly this. Reach for it first.</p><h3>HTTP Session</h3><pre>from contextlib import contextmanager<br>import requests<br><br>@contextmanager<br>def http_session(token: str):<br>    session = requests.Session()<br>    session.headers.update({&quot;Authorization&quot;: f&quot;Bearer {token}&quot;})<br>    try:<br>        yield session<br>    finally:<br>        session.close()<br><br>with http_session(&quot;my-api-token&quot;) as s:<br>    response = s.get(&quot;https://api.example.com/users/42&quot;)</pre><h3>The Exception Trap in __exit__</h3><p>This is the gotcha that bites every implementor once.</p><p>__exit__ receives three arguments: exc_type, exc_val, exc_tb. They’re None if no exception occurred. If an exception did occur:</p><ul><li>Return False (or None): the exception propagates normally. This is almost always what you want.</li><li>Return True: the exception is suppressed. The with block exits cleanly. Use this only when suppression is the explicit intent (e.g., contextlib.suppress).</li></ul><pre>from contextlib import suppress<br><br>with suppress(FileNotFoundError):<br>    open(&quot;nonexistent.txt&quot;)<br># no exception raised — suppress returns True internally</pre><p>The dangerous version: raising a <em>new</em> exception inside __exit__:</p><pre>class Broken:<br>    def __enter__(self):<br>        return self<br><br>    def __exit__(self, exc_type, exc_val, exc_tb):<br>        raise RuntimeError(&quot;cleanup failed&quot;)  # silently replaces original exception!<br><br>with Broken():<br>    raise ValueError(&quot;original problem&quot;)<br><br># You see: RuntimeError(&quot;cleanup failed&quot;)<br># The ValueError is gone. Good luck debugging that.</pre><p>If your cleanup code can raise, wrap it:</p><pre>def __exit__(self, exc_type, exc_val, exc_tb):<br>    try:<br>        self._conn.close()<br>    except Exception as cleanup_err:<br>        # log it, don&#39;t raise — preserve the original exception<br>        print(f&quot;Warning: cleanup failed: {cleanup_err}&quot;)<br>    return False</pre><h3>Composing Resources with ExitStack</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pyIGtcc_6zECg1Bzqu0s-g.png" /></figure><p>Nesting with statements works for two resources. For N resources, opening a dynamic list of files, managing connections from a pool, applying patches in a loop, nested with is not the answer.</p><p>contextlib.ExitStack is:</p><pre>from contextlib import ExitStack<br><br>file_paths = [&quot;a.txt&quot;, &quot;b.txt&quot;, &quot;c.txt&quot;]<br><br>with ExitStack() as stack:<br>    files = [stack.enter_context(open(p)) for p in file_paths]<br>    # all files open here<br>    for f in files:<br>        print(f.readline())<br># all files closed here, in reverse order, even if one raised<br><br># Output (contents of first line of each file):<br># &lt;first line of a.txt&gt;<br># &lt;first line of b.txt&gt;<br># &lt;first line of c.txt&gt;</pre><p>ExitStack also lets you conditionally register cleanup:</p><pre>import threading<br>from contextlib import ExitStack<br><br>_db_lock = threading.Lock()<br>needs_lock = True  # determined at runtime<br><br>with ExitStack() as stack:<br>    conn = stack.enter_context(db_connection(&quot;mydb.db&quot;))<br>    if needs_lock:<br>        stack.enter_context(_db_lock)<br>    # cleanup order is LIFO: lock released before connection closed</pre><p>And you can transfer ownership out of the stack:</p><pre>DSN = &quot;mydb.db&quot;<br>RESOURCE_ID = &quot;resource-1&quot;<br><br>_locks: dict = {}<br><br>def open_resources():<br>    with ExitStack() as stack:<br>        conn = stack.enter_context(db_connection(DSN))<br>        lock = _locks.setdefault(RESOURCE_ID, threading.Lock())<br>        stack.enter_context(lock)<br>        # transfer cleanup responsibility to caller<br>        return conn, lock, stack.pop_all()<br><br>conn, lock, cleanup = open_resources()<br>try:<br>    pass  # process(conn, lock)<br>finally:<br>    cleanup.close()</pre><h3>Context Managers in Testing</h3><p>unittest.mock.patch is already a context manager. This matters for mock scope:</p><pre>from unittest.mock import patch<br><br>def test_send_email():<br>    with patch(&quot;myapp.mailer.send&quot;) as mock_send:<br>        trigger_notification(user_id=42)<br>        mock_send.assert_called_once_with(to=&quot;user@example.com&quot;)<br>    # mock_send.send is restored here, not after the whole test file</pre><p>The with block makes the mock’s lifetime explicit and visible. Using @patch as a decorator is fine, but with patch(...) scopes the mock to the exact lines that need it, which makes the test easier to read at a glance.</p><p>With ExitStack, you can apply multiple patches cleanly:</p><pre>def test_complex_flow():<br>    with ExitStack() as stack:<br>        mock_db = stack.enter_context(patch(&quot;myapp.db.connect&quot;))<br>        mock_cache = stack.enter_context(patch(&quot;myapp.cache.get&quot;))<br>        mock_email = stack.enter_context(patch(&quot;myapp.mailer.send&quot;))<br><br>        run_full_pipeline()<br><br>        mock_db.assert_called_once()<br>        mock_email.assert_called_once()</pre><h3>Gotchas and Tradeoffs</h3><p>1. return False vs return True in __exit__: Returning True suppresses exceptions. Most implementations should return False (or nothing, which is falsy). Accidentally returning True on an exception path makes bugs disappear silently.</p><p>2. Exceptions in __exit__ replace the original exception: If your cleanup code raises, the original exception is lost. Always wrap cleanup in try/except inside __exit__, log the cleanup failure, and let the original propagate.</p><p>3. @contextmanager must yield exactly once: A generator that returns without yielding raises RuntimeError. A generator that yields twice raises RuntimeError on the second yield. Neither is recoverable at the call site.</p><p>4. Don’t use context managers for logic: If your __exit__ is doing business logic (not just resource cleanup), you’ve turned a resource protocol into a control-flow mechanism. Future maintainers will curse you. Keep __exit__ limited to cleanup.</p><p>5. When NOT to use this pattern: If you have no cleanup to perform, don’t invent a context manager. A simple function is more readable. Context managers solve the “must release after acquire” problem; they’re not a general-purpose code organization tool.</p><h3>Takeaways</h3><ul><li>Any object with __enter__ and __exit__ works as a context manager: files, locks, connections, timers, mock patches, anything.</li><li>@contextmanager with a yield in a try/finally is the fastest path for stateless managers.</li><li>ExitStack is the correct tool for N resources. Don’t nest with statements for dynamic resource sets.</li><li>The one-sentence mental model: if your code has acquire, use, release, it belongs in a context manager.</li></ul><h3>Conclusion</h3><p>The with statement is not a file-closing helper. It’s Python’s resource lifecycle protocol. Once you see that, try/finally blocks for database connections, thread locks, HTTP sessions, and temp directories start to look like what they are: the same pattern, written out by hand each time.</p><p>The refactor is usually small: a @contextmanager function is typically under ten lines. The payoff is that acquisition and release live together, composability comes free, and the code tells the reader what it means rather than how it cleans up.</p><p>What resource in your codebase has the most defensive try/finally scaffolding around it right now? That’s your first refactor.</p><p>If you found this useful, the next article in the series covers __enter__/__exit__ in async code: async with, asynccontextmanager, and how cleanup works when coroutines are involved.</p><p>If you found this post helpful, don’t forget to <strong>👏 clap</strong> to show your support!</p><p>I’d also love to hear your thoughts and insights on the techniques covered in this article. 💡 Feel free to share your experiences in the <strong>comments</strong> 💬.</p><figure><a href="https://medium.com/@rgr5882/subscribe"><img alt="" src="https://cdn-images-1.medium.com/max/780/1*HaafLJIgmLZMblLS4wtE3w.png" /></a></figure><h3>Connect with Me on LinkedIn!</h3><p>You can also connect with me on <a href="https://www.linkedin.com/in/ricardogarciaramirez/"><strong>LinkedIn</strong> </a>for updates on my latest posts and projects. 🌐 Let’s keep the conversation going!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d4bbe9c9ac99" width="1" height="1" alt=""><hr><p><a href="https://blog.devgenius.io/when-try-finally-becomes-a-code-smell-and-the-fix-d4bbe9c9ac99">When try/finally Becomes a Code Smell (And the Fix)</a> was originally published in <a href="https://blog.devgenius.io/">Dev Genius</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Dependency Inversion in ML Training Pipelines]]></title>
            <link>https://python.plainenglish.io/dependency-inversion-in-ml-training-pipelines-d358de8c5851?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/d358de8c5851</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[data-pipeline]]></category>
            <category><![CDATA[dependency-inversion]]></category>
            <category><![CDATA[coding-best-practices]]></category>
            <category><![CDATA[machine-learning]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Mon, 13 Jul 2026 06:20:08 GMT</pubDate>
            <atom:updated>2026-07-13T06:20:08.631Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How protocols and abstract classes decouple your model, data loader, and optimizer before they become a refactoring nightmare.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hdgARMb0ZZwSODVXIxb6YQ.png" /></figure><h3>The Training Script That Works Until It Doesn’t</h3><p>You write a training script over a weekend. It works. The model trains, the loss curve looks reasonable, and the weights land in an S3 bucket. You call it done.</p><p>Three months later, the data team migrates to a streaming format. You update your DataLoader class. But the training loop assumed .to(&quot;cuda&quot;) on a torch.Tensor. Now three other spots break. You fix those. Then a colleague asks for a CPU-only run for their laptop. You add an if-else. Then someone wants to log to MLflow instead of wandb. Another if-else. Then you want to write a unit test for the training loop and realize you can’t, because instantiating the model requires a GPU and loading the data requires the production bucket.</p><p>You now have a training script with five if-else branches, two environment variables that must be set correctly, and no tests.</p><p>I already talked about DIP in another <a href="https://blog.devgenius.io/dependency-inversion-principle-in-python-depend-on-abstractions-23e8ee9ec77b">article </a>within the SOLID series, but as I talked in my <a href="https://medium.com/python-in-plain-english/the-interface-segregation-principle-for-python-protocols-8090dfcbcbc0">last article about ISP</a>, I want to reramp these 2 elements in the context of ML and DS.</p><p>By the end of this article, you will be able to apply the DIP to an ML training loop, replacing hard-coded concrete classes with injectable abstractions that make your pipeline testable, swappable, and framework-agnostic at the seams that matter.</p><h3>What Dependency Inversion Actually Says</h3><p>In plain terms, your training loop is a high-level module. It orchestrates the training process. The DataLoader, the Model, and the Logger are low-level modules. They do the work. DIP says the training loop should not know which specific DataLoader or Logger it’s using. It should only know what interface those components expose.</p><h3>Where ML Training Pipelines Violate DIP</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*s1I9SkK_6svgd4KxU8Pltw.png" /></figure><p>Here is a typical training function:</p><pre>import torch<br>import torch.nn as nn<br>from torch.utils.data import DataLoader<br>import wandb<br><br>def train(data_path: str, epochs: int = 10, lr: float = 0.001) -&gt; None:<br>    dataset = MyCSVDataset(data_path)           # concrete<br>    loader = DataLoader(dataset, batch_size=32)  # concrete<br>    model = LinearRegressor(input_dim=10)        # concrete<br>    optimizer = torch.optim.Adam(model.parameters(), lr=lr)<br>    wandb.init(project=&quot;regression-experiment&quot;)  # concrete<br><br>    model.train()<br>    for epoch in range(epochs):<br>        for X, y in loader:<br>            X, y = X.to(&quot;cuda&quot;), y.to(&quot;cuda&quot;)<br>            optimizer.zero_grad()<br>            loss = nn.MSELoss()(model(X), y)<br>            loss.backward()<br>            optimizer.step()<br>        wandb.log({&quot;loss&quot;: loss.item()})</pre><p>Every concrete dependency is created inside the function. To test this, you need a CSV file, a GPU, and a wandb account. To swap the logger, you must edit the training function itself.</p><p>The coupling is not between the function and its behavior. The coupling is between the function and its dependencies’ implementations.</p><h3>Defining What You Need, Not What You Have</h3><p>Python’s typing.Protocol lets you define structural interfaces without requiring inheritance. A class satisfies a protocol if it has the right methods, regardless of what it inherits from. This is the right tool for ML components, because you often cannot modify third-party classes like torch.nn.Module.</p><p>Define three protocols that describe what the training loop actually needs:</p><pre>from typing import Protocol, Iterator, runtime_checkable<br>from torch.nn import Parameter<br>import torch<br><br>@runtime_checkable<br>class ModelProtocol(Protocol):<br>    def __call__(self, x: torch.Tensor) -&gt; torch.Tensor: ...<br>    def parameters(self) -&gt; Iterator[Parameter]: ...<br>    def train(self, mode: bool = True): ...<br><br>@runtime_checkable<br>class BatchIteratorProtocol(Protocol):<br>    def __iter__(self) -&gt; Iterator[tuple[torch.Tensor, torch.Tensor]]: ...<br><br>@runtime_checkable<br>class LoggerProtocol(Protocol):<br>    def log(self, metrics: dict[str, float], step: int) -&gt; None: ...</pre><p>@runtime_checkable allows isinstance(obj, ModelProtocol) checks, which is useful for debugging. The ... body on each method is not a placeholder; it is the correct syntax for Protocol method stubs.</p><p>ModelProtocol declares __call__ rather than forward because that is what callers actually invoke. torch.nn.Module satisfies this protocol because all Modules are callable: module.__call__ runs forward passes and hooks. You do not need to change any existing model code.</p><h3>The Refactored Training Loop</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MK3Kip9z7-GjFbk74tTD9w.png" /></figure><p>With protocols in place, rewrite train() to accept abstractions instead of concrete types:</p><pre>def train(<br>    model: ModelProtocol,<br>    loader: BatchIteratorProtocol,<br>    logger: LoggerProtocol,<br>    epochs: int = 10,<br>    lr: float = 0.001,<br>    device: str = &quot;cpu&quot;,<br>) -&gt; None:<br>    optimizer = torch.optim.Adam(model.parameters(), lr=lr)<br>    model.train()<br><br>    for epoch in range(epochs):<br>        loss = torch.tensor(0.0)<br>        for X, y in loader:<br>            X, y = X.to(device), y.to(device)<br>            optimizer.zero_grad()<br>            loss = torch.nn.functional.mse_loss(model(X), y)<br>            loss.backward()<br>            optimizer.step()<br>        logger.log({&quot;loss&quot;: loss.item()}, step=epoch)</pre><p>The training loop no longer imports wandb, DataLoader, or any specific model class. It operates on contracts. The caller decides which implementations to pass.</p><p>Your production entry point still uses the real classes:</p><pre># LinearRegressor, MyCSVDataset, WandbLogger are your own implementations<br>model = LinearRegressor(input_dim=10).to(&quot;cuda&quot;)<br>loader = DataLoader(MyCSVDataset(&quot;s3://bucket/train.csv&quot;), batch_size=32)<br>logger = WandbLogger(project=&quot;regression-experiment&quot;)<br><br>train(model, loader, logger, device=&quot;cuda&quot;)</pre><p>Nothing changed in how you call it from production. Everything changed in how you can test it.</p><h3>Testing with Fakes, Not Mocks</h3><p>You can now write a test that runs in under one second, without a GPU and without a real dataset:</p><pre>import torch<br><br>class FakeModel:<br>    def __init__(self) -&gt; None:<br>        self._w = torch.nn.Parameter(torch.zeros(10, 1))<br><br>    def __call__(self, x: torch.Tensor) -&gt; torch.Tensor:<br>        return x @ self._w  # connected to _w; backward() has a valid grad_fn<br><br>    def parameters(self):<br>        return iter([self._w])<br><br>    def train(self, mode: bool = True):<br>        return self<br><br><br>class FakeLoader:<br>    def __iter__(self):<br>        for _ in range(5):<br>            yield torch.randn(8, 10), torch.randn(8, 1)<br><br><br>class FakeLogger:<br>    def __init__(self) -&gt; None:<br>        self.logs: list[dict] = []<br><br>    def log(self, metrics: dict[str, float], step: int) -&gt; None:<br>        self.logs.append({&quot;step&quot;: step, **metrics})<br><br><br>def test_train_records_one_log_entry_per_epoch() -&gt; None:<br>    logger = FakeLogger()<br>    train(FakeModel(), FakeLoader(), logger, epochs=3, device=&quot;cpu&quot;)<br>    assert len(logger.logs) == 3<br>    assert &quot;loss&quot; in logger.logs[0]</pre><p>The fakes are plain Python classes. No mock library. No patching. No side effects. FakeModel uses a real trainable parameter (self._w) so the loss computation produces a valid gradient graph and loss.backward() succeeds. The test verifies that train() calls logger.log() once per epoch: the actual contract you care about.</p><h3>Gotchas</h3><p><strong>Don’t Protocol everything. </strong>The optimizer in the refactored example is still torch.optim.Adam, created inside train(). That is deliberate. If the optimizer is never swapped in practice, abstracting it adds indirection with no payoff. Apply DIP at the seams where change actually happens, not preemptively across every dependency.</p><p><strong>Protocol satisfaction is not checked at import time.</strong> If FakeModel is missing the train method, Python will not raise an error until the method is called. Adding assert isinstance(model, ModelProtocol) at the start of train() catches this earlier. Without it, you get an AttributeError mid-training, not at injection time.</p><p><strong>Protocol vs ABC: know when to use which.</strong> Protocol gives structural typing (duck typing with a declared shape). ABC (abstract base class) gives nominal typing with enforced inheritance. Use Protocol for third-party classes you do not own. Use ABC when you own all implementations and want the interpreter to enforce the contract at subclass definition time.</p><h3>Takeaways</h3><ul><li>Dependency injection via function arguments is enough. You do not need a DI framework.</li><li>A training loop that accepts abstractions can be tested with fake components in milliseconds, without GPU or production data.</li><li>Apply DIP at the seams where change actually happens: data source, logger, model backbone. Not preemptively everywhere.</li></ul><p>A training loop that accepts protocols instead of concrete classes is not more complex. It is more honest: it declares exactly what it needs and lets the caller decide how to provide it.</p><p>The question worth sitting with: In your current training codebase, how many dependencies are created inside the training function instead of passed into it? That count is your DIP debt.</p><p>If this pattern solved a problem for you, the same principle applied to data preprocessing pipelines covers similar ground in a different direction.</p><p>If you found this post helpful, don’t forget to <strong>👏 clap</strong> to show your support!</p><p>I’d also love to hear your thoughts and insights on the techniques covered in this article. 💡 Feel free to share your experiences in the <strong>comments</strong> 💬.</p><figure><a href="https://medium.com/@rgr5882/subscribe"><img alt="" src="https://cdn-images-1.medium.com/max/780/1*HaafLJIgmLZMblLS4wtE3w.png" /></a></figure><h3>Connect with Me on LinkedIn!</h3><p>You can also connect with me on <a href="https://www.linkedin.com/in/ricardogarciaramirez/"><strong>LinkedIn</strong> </a>for updates on my latest posts and projects. 🌐 Let’s keep the conversation going!</p><h3>Before you go</h3><ul><li>Please take a moment to like the post and follow the writer!</li><li>Did you know that over 400,000 developers share what they’re building, learning, and discovering across our platforms every month? Learn how you can contribute <a href="https://plainenglish.io/write-for-us">here</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d358de8c5851" width="1" height="1" alt=""><hr><p><a href="https://python.plainenglish.io/dependency-inversion-in-ml-training-pipelines-d358de8c5851">Dependency Inversion in ML Training Pipelines</a> was originally published in <a href="https://python.plainenglish.io/">Python in Plain English</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Stop Writing Integration Tests You Can’t Run Locally]]></title>
            <link>https://levelup.gitconnected.com/stop-writing-integration-tests-you-cant-run-locally-133450a3d539?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/133450a3d539</guid>
            <category><![CDATA[continuos-integration]]></category>
            <category><![CDATA[cicd]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[integration-testing]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Mon, 06 Jul 2026 14:25:57 GMT</pubDate>
            <atom:updated>2026-07-06T14:25:57.474Z</atom:updated>
            <content:encoded><![CDATA[<p>If your integration tests require a live cloud environment, you’ve outsourced your feedback loop to CI. You will pay for it every time something breaks.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*g6xlQ4LjvxKuSXk05Ng9xw.png" /></figure><h3>The Eight-Minute Debug Loop</h3><p>You push a fix. The CI pipeline starts. Eight minutes later, the integration test fails with connection refused on a Postgres instance that doesn’t exist in your local environment. You add a debug print statement and push again. Eight more minutes. The test supposed to catch bugs has become the bug, not in your application code, but in how you designed the test.</p><p>This loop is not a CI problem. It is a test design problem.</p><p>The most common response is to add @pytest.mark.integration and tell the team: “Run unit tests locally, let CI handle the integration tests.” This feels pragmatic. In practice, it means you’ve built a second feedback loop that costs ten minutes per iteration, runs against shared infrastructure that other branches also modify, and fails in ways you cannot reproduce on your own machine.</p><p>By the end of this article, you will have a pattern for writing integration tests that run identically on a developer laptop and in CI using testcontainers or docker-compose, with no mocking and no dependency on external services.</p><h3>What Qualifies as an Integration Test</h3><p>An integration test verifies that two or more components work correctly together, where at least one component is real infrastructure: a database, a message queue, a cache, a file system. It is not a unit test with a mock database client. It is not an end-to-end test that drives a browser through a deployed application. It sits between those two.</p><p>The definition matters because “integration test” gets used loosely. If your test mocks the database, it is testing your code’s assumptions about the database, not the database behavior. That distinction becomes critical when you’re debugging a query that behaves differently under a real query planner than under your mock.</p><h3>Why “Just Run It in CI” Fails</h3><p>The most immediate cost is the feedback loop. A unit test gives you a result in seconds. A CI-only integration test gives you a result in eight to fifteen minutes, depending on your pipeline setup. If you’re iterating on a query or a service interaction, you run that loop multiple times per fix.</p><p>The second cost is environmental drift. CI integration tests usually run against shared staging databases or shared containers. Other branches write to the same tables. Migrations run in unpredictable orders. Tests that pass alone fail in combination because a previous test left a dirty state. You cannot reproduce this locally because you cannot replicate the exact sequence that CI ran.</p><p>The third cost is the false confidence gradient. Your unit tests pass locally, and your integration tests pass in CI, so you assume coverage. But your integration tests are testing a different environment than production. Subtle differences in Postgres versions, Redis configuration, or network latency between services exist between your CI environment and production. These differences show up as bugs, not test failures, which means they skip your test suite entirely.</p><h3>The Seam Problem</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_J-zaiglV-AffCUuzL2B-w.png" /></figure><p>The root cause of CI-only integration tests is almost always seam design. A seam is the boundary between your application code and external dependencies. When you write:</p><pre>import os<br>import psycopg2<br><br>conn = psycopg2.connect(os.environ[&quot;DATABASE_URL&quot;])</pre><p>You have created a hard seam. The database URL is baked into the module at import time. To run this test locally, you must either set DATABASE_URL to a real database URL or mock os.environ, which defeats the point of an integration test.</p><p>The fix is injectable configuration:</p><pre>def get_connection(database_url: str) -&gt; psycopg2.extensions.connection:<br>    return psycopg2.connect(database_url)</pre><p>Now your test controls the URL. It can pass a URL pointing to a local container, a CI container, or a test-specific database. The application code does not change, only what gets passed in.</p><p>This is not a new idea. It is dependency injection applied to infrastructure. The reason it gets skipped in data and ML codebases is that scripts often read directly from environment variables at the top of a file, and that pattern propagates.</p><h3>Testcontainers: Real Infrastructure Per Test Session</h3><p>Testcontainers is a library that spins up real Docker containers from within your test session, runs your tests against them, and destroys them when the session ends. Your test gets a real Postgres instance, not a mock. The container lifecycle is managed by the test framework.</p><p>Install the required libraries:</p><pre>pip install &quot;testcontainers[postgres]&gt;=4.0&quot; sqlalchemy psycopg2-binary</pre><p>The version pin on testcontainers matters: 4.x returns a postgresql+psycopg2:// URL from get_connection_url(), which is required by SQLAlchemy 2.x. Earlier versions return a bare postgresql:// URL that triggers a deprecation warning.</p><p>A minimal pytest fixture:</p><pre>import pytest<br>from testcontainers.postgres import PostgresContainer<br>from sqlalchemy import create_engine, text<br><br><br>@pytest.fixture(scope=&quot;session&quot;)<br>def postgres_url():<br>    with PostgresContainer(&quot;postgres:16&quot;) as postgres:<br>        yield postgres.get_connection_url()<br><br><br>@pytest.fixture(scope=&quot;session&quot;)<br>def engine(postgres_url):<br>    engine = create_engine(postgres_url)<br>    with engine.connect() as conn:<br>        conn.execute(text(&quot;&quot;&quot;<br>            CREATE TABLE IF NOT EXISTS events (<br>                id SERIAL PRIMARY KEY,<br>                name TEXT NOT NULL,<br>                created_at TIMESTAMP DEFAULT NOW()<br>            )<br>        &quot;&quot;&quot;))<br>        conn.commit()<br>    return engine</pre><p>A test using this fixture:</p><pre>def test_insert_and_retrieve_event(engine):<br>    with engine.connect() as conn:<br>        conn.execute(<br>            text(&quot;INSERT INTO events (name) VALUES (:name)&quot;),<br>            {&quot;name&quot;: &quot;test_event&quot;}<br>        )<br>        conn.commit()<br>        result = conn.execute(text(&quot;SELECT name FROM events&quot;)).fetchall()<br><br>    assert any(r[0] == &quot;test_event&quot; for r in result)</pre><p>The scope=&quot;session&quot; on the fixture means the container starts once per test session, not once per test. This keeps startup overhead manageable. Because the engine is session-scoped, rows inserted by one test persist for other tests in the same session. The assertion checks for the specific row rather than an exact count.</p><h3>Docker-Compose as an Alternative</h3><p>If your integration tests require multiple services, such as Postgres plus Redis plus a message queue, testcontainers can become verbose. Docker-compose is simpler in this case.</p><p>Create a docker-compose.test.yml:</p><pre>services:<br>  postgres:<br>    image: postgres:16<br>    environment:<br>      POSTGRES_USER: test<br>      POSTGRES_PASSWORD: test<br>      POSTGRES_DB: testdb<br>    ports:<br>      - &quot;5433:5432&quot;<br>    healthcheck:<br>      test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U test&quot;]<br>      interval: 5s<br>      timeout: 5s<br>      retries: 5<br><br>  redis:<br>    image: redis:7<br>    ports:<br>      - &quot;6380:6379&quot;</pre><p>The healthcheck block on the postgres service ensures the container is ready to accept connections before your tests start. Without it, pytest may begin before Postgres finishes initialising, producing intermittent connection refused errors in CI.</p><p>Start the services before your test run:</p><pre>docker compose -f docker-compose.test.yml up -d --wait<br>pytest<br>docker compose -f docker-compose.test.yml down</pre><p>The --wait flag tells docker compose to wait for all healthchecks to pass before returning. Teams typically wrap these three commands in a make test target to avoid running them manually.</p><p>Your tests read from fixed local ports (localhost:5433, localhost:6380) that you set in a .env.test file or pass directly. CI runs the same compose file in its Docker environment. The test code does not change between environments because the URL is injected from configuration, not hardcoded.</p><p>The tradeoff: you need to manage the compose lifecycle explicitly. Testcontainers handles this automatically; docker-compose does not. For simple single-service cases, testcontainers is less setup. For multi-service cases with stable service definitions, docker-compose is easier to read and maintain.</p><h3>Takeaways</h3><ul><li>A CI-only integration test iteration takes 8 to 15 minutes per cycle. A local test gives you a result in seconds. When you’re iterating on a bug fix, you run that loop multiple times. The feedback cost is not hypothetical. Treat local runnability as a hard constraint.</li><li>Hard-coded os.environ reads at module level are the most common reason integration tests become CI-only. Replace them with injectable parameters at the function or class boundary.</li><li>Testcontainers spins up real Docker containers per test session, giving you real infrastructure — the same database engine and query planner, not a mock — with automatic lifecycle management.</li><li>Docker-compose is the better choice for multi-service test environments with stable service definitions. Testcontainers is the better choice for single-service cases where you want automatic teardown inside the test runner.</li><li>Document Docker as a development dependency in your README, your Makefile, and your onboarding guide. A test suite no one can run is not a test suite.</li></ul><p>The change is not large. Injectable configuration replaces hard-coded environment reads. A testcontainer fixture or a docker-compose file replaces the assumption of a live external service. The discipline of asking “can I run this right now, on my laptop, without VPN or staging credentials?” changes how you design tests from the start.</p><p>What would you have to change in your current test suite to make every integration test runnable locally today?</p><p>If you found this post helpful, don’t forget to <strong>👏 clap</strong> to show your support!</p><p>I’d also love to hear your thoughts and insights on the techniques covered in this article. 💡 Feel free to share your experiences in the <strong>comments</strong> 💬.</p><figure><a href="https://medium.com/@rgr5882/subscribe"><img alt="" src="https://cdn-images-1.medium.com/max/780/1*HaafLJIgmLZMblLS4wtE3w.png" /></a></figure><h3>Connect with Me on LinkedIn!</h3><p>You can also connect with me on <a href="https://www.linkedin.com/in/ricardogarciaramirez/"><strong>LinkedIn</strong> </a>for updates on my latest posts and projects. 🌐 Let’s keep the conversation going!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=133450a3d539" width="1" height="1" alt=""><hr><p><a href="https://levelup.gitconnected.com/stop-writing-integration-tests-you-cant-run-locally-133450a3d539">Stop Writing Integration Tests You Can’t Run Locally</a> was originally published in <a href="https://levelup.gitconnected.com/">Level Up Coding</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Interface Segregation Principle for Python Protocols]]></title>
            <link>https://python.plainenglish.io/the-interface-segregation-principle-for-python-protocols-8090dfcbcbc0?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/8090dfcbcbc0</guid>
            <category><![CDATA[isp]]></category>
            <category><![CDATA[clean-code]]></category>
            <category><![CDATA[protocol]]></category>
            <category><![CDATA[best-practices]]></category>
            <category><![CDATA[python]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Mon, 06 Jul 2026 06:44:51 GMT</pubDate>
            <atom:updated>2026-07-06T06:44:51.090Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Small protocols compose. Large protocols constrain. Here is how to tell the difference.</em></p><h3>The Protocol That Grew Too Wide</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*h7i47SuPPsdkDp10v1l1LA.png" /></figure><p>You define a DataSource protocol with six methods: load, save, validate, schema, preview, and count. It looks clean. One concept, one interface.</p><p>Then you audit the callers. Your training pipeline calls only load. Your validation module calls only validate and schema. Your reporting code calls only preview and count. No single caller uses more than two of the six methods, but every caller depends on all six.</p><p>The problem surfaces when you write a test double for the training pipeline. You must implement all six methods or your static type checker complains. When a new contributor adds a CSV reader with no save capability, they either add a save that raises NotImplementedError or they abandon protocols and fall back to Any. The interface you designed to enforce good contracts became a source of useless coupling.</p><p>This is an <a href="https://medium.com/dev-genius/interface-segregation-principle-in-python-keep-interfaces-small-2d7c58bf0401">Interface Segregation Principle</a> violation, and Python’s Protocol class makes it both easy to create and straightforward to fix.</p><p>I’ve already talked about this when I focused on SOLID principles early this year, but since I just had an interview call this week and they asked so much about my main issues with SOLID implementation in my day-to-day, I decided to revamp this one with a more DS and ETL focus.</p><p>By the end of this article, you will have replaced a fat protocol with a set of narrow, composable protocols; verified the design with mypy, and confirmed that your implementation class satisfies all of them without any inheritance.</p><h3>What ISP Actually Says</h3><p>You can re-read the whole <a href="https://medium.com/dev-genius/interface-segregation-principle-in-python-keep-interfaces-small-2d7c58bf0401">article </a>where I talk about this, but in a nutshell, clients should not be forced to depend on methods they do not use.</p><p>In Python, typing.Protocol (we have it since Python 3.8) is structural typing. A class satisfies a protocol if it has the required attributes and methods. No inheritance or registration is needed. So a protocol is not a description of a class. It is a description of what a specific caller needs. If a caller needs one method, the protocol should declare one method.</p><h3>The Fat Protocol in Practice</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lM729PoMhMOzCtYdarZJcw.png" /></figure><p>Here is the problem made concrete. Assume you have a data ingestion system where different components consume the same source object.</p><pre>from typing import Protocol<br>import pandas as pd<br><br><br>class DataSource(Protocol):<br>    def load(self) -&gt; pd.DataFrame: ...<br>    def save(self, df: pd.DataFrame) -&gt; None: ...<br>    def validate(self, df: pd.DataFrame) -&gt; bool: ...<br>    def schema(self) -&gt; dict[str, str]: ...<br>    def preview(self, n: int = 5) -&gt; pd.DataFrame: ...<br>    def count(self) -&gt; int: ...<br><br><br>def train_model(source: DataSource) -&gt; None:<br>    _df = source.load()<br>    # source.save, source.validate, source.schema,<br>    # source.preview, source.count are never called here<br><br><br>def check_schema(source: DataSource, df: pd.DataFrame) -&gt; bool:<br>    _schema = source.schema()<br>    return source.validate(df)<br><br><br>def generate_report(source: DataSource) -&gt; None:<br>    print(source.preview())<br>    print(f&quot;Total rows: {source.count()}&quot;)</pre><p>Every function takes DataSource. Every function depends on six methods. None of them uses more than two.</p><p>The dependency is not just conceptual. It is enforced by the type checker. Any object passed to train_model must satisfy the full six-method contract, even though train_model will never touch five of them.</p><h3>Split the Protocol Around the Caller</h3><p>The fix is to define each protocol based on what a single caller requires, not on what an existing class provides.</p><pre>from typing import Protocol<br>import pandas as pd<br><br><br>class Loadable(Protocol):<br>    def load(self) -&gt; pd.DataFrame: ...<br><br><br>class Saveable(Protocol):<br>    def save(self, df: pd.DataFrame) -&gt; None: ...<br><br><br>class Validatable(Protocol):<br>    def validate(self, df: pd.DataFrame) -&gt; bool: ...<br>    def schema(self) -&gt; dict[str, str]: ...<br><br><br>class Previewable(Protocol):<br>    def preview(self, n: int = 5) -&gt; pd.DataFrame: ...<br>    def count(self) -&gt; int: ...<br><br><br>def train_model(source: Loadable) -&gt; None:<br>    _df = source.load()<br><br><br>def check_schema(source: Validatable, df: pd.DataFrame) -&gt; bool:<br>    _schema = source.schema()<br>    return source.validate(df)<br><br><br>def generate_report(source: Previewable) -&gt; None:<br>    print(source.preview())<br>    print(f&quot;Total rows: {source.count()}&quot;)</pre><p>Each function now declares exactly what it needs. A function that calls load depends on Loadable. Nothing else.</p><h3>Classes Satisfy Multiple Narrow Protocols for Free</h3><p>Splitting protocols does not require splitting classes. A single implementation class can satisfy all four protocols without inheriting from any of them.</p><pre>class InMemoryDataSource:<br>    def __init__(self, data: pd.DataFrame, required_columns: list[str]) -&gt; None:<br>        self._data = data<br>        self.required_columns = required_columns<br><br>    def load(self) -&gt; pd.DataFrame:<br>        return self._data.copy()<br><br>    def save(self, df: pd.DataFrame) -&gt; None:<br>        self._data = df.copy()<br><br>    def validate(self, df: pd.DataFrame) -&gt; bool:<br>        return all(col in df.columns for col in self.required_columns)<br><br>    def schema(self) -&gt; dict[str, str]:<br>        return {col: str(dtype) for col, dtype in self._data.dtypes.items()}<br><br>    def preview(self, n: int = 5) -&gt; pd.DataFrame:<br>        return self._data.head(n)<br><br>    def count(self) -&gt; int:<br>        return len(self._data)<br><br><br>sample = pd.DataFrame({&quot;id&quot;: [1, 2, 3], &quot;value&quot;: [10, 20, 30]})<br>source = InMemoryDataSource(sample, required_columns=[&quot;id&quot;, &quot;value&quot;])<br><br>train_model(source)                          # OK: satisfies Loadable<br>print(check_schema(source, source.load()))   # OK: satisfies Validatable<br>generate_report(source)                      # OK: satisfies Previewable</pre><pre>True<br>   id  value<br>0   1     10<br>1   2     20<br>2   3     30<br>Total rows: 3</pre><p>mypy accepts all three calls without any # type: ignore comments. Python’s structural typing checks the presence of methods, not the inheritance chain. The class implements the methods. The protocols describe them. The type checker connects the two at call sites.</p><h3>Verification with mypy</h3><p>The claim is that a class implementing only load satisfies Loadable but not the fat DataSource. Here is the proof.</p><pre># minimal_check.py<br>from typing import Protocol<br>import pandas as pd<br><br><br>class Loadable(Protocol):<br>    def load(self) -&gt; pd.DataFrame: ...<br><br><br>class DataSource(Protocol):<br>    def load(self) -&gt; pd.DataFrame: ...<br>    def save(self, df: pd.DataFrame) -&gt; None: ...<br>    def validate(self, df: pd.DataFrame) -&gt; bool: ...<br>    def schema(self) -&gt; dict[str, str]: ...<br>    def preview(self, n: int = 5) -&gt; pd.DataFrame: ...<br>    def count(self) -&gt; int: ...<br><br><br>class MinimalLoader:<br>    def load(self) -&gt; pd.DataFrame:<br>        return pd.DataFrame({&quot;id&quot;: [1], &quot;value&quot;: [10]})<br><br><br>def train_model_narrow(source: Loadable) -&gt; None:<br>    _df = source.load()<br><br><br>def train_model_fat(source: DataSource) -&gt; None:<br>    _df = source.load()<br><br><br>train_model_narrow(MinimalLoader())   # accepted<br>train_model_fat(MinimalLoader())      # rejected: missing 5 methods</pre><pre>$ mypy --strict minimal_check.py<br>minimal_check.py:32: error: Argument 1 to &quot;train_model_fat&quot; has incompatible type &quot;MinimalLoader&quot;; expected &quot;DataSource&quot;  [arg-type]<br>Found 1 error in 1 file (checked 1 source file)</pre><p>The narrow protocol accepts MinimalLoader without modification. The fat protocol rejects it because five methods are absent, even though train_model_fat never calls them.</p><h3>Test Doubles Get Simpler</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*be6226MBi9H_o4v1vvnjJQ.png" /></figure><p>The ISP violation in protocols is usually invisible until you write a test. That is when the coupling becomes concrete.</p><pre># BEFORE: test double for train_model must satisfy all six methods<br>class FakeSource:<br>    def load(self) -&gt; pd.DataFrame:<br>        return pd.DataFrame({&quot;id&quot;: [1], &quot;value&quot;: [42]})<br><br>    def save(self, df: pd.DataFrame) -&gt; None: ...       # never called<br>    def validate(self, df: pd.DataFrame) -&gt; bool: ...   # never called<br>    def schema(self) -&gt; dict[str, str]: ...             # never called<br>    def preview(self, n: int = 5) -&gt; pd.DataFrame: ...  # never called<br>    def count(self) -&gt; int: ...                         # never called</pre><pre># AFTER: test double for train_model needs exactly one method<br>class FakeLoadable:<br>    def load(self) -&gt; pd.DataFrame:<br>        return pd.DataFrame({&quot;id&quot;: [1], &quot;value&quot;: [42]})</pre><p>The reduction is not aesthetic. Fewer stub methods means fewer places for a type signature mismatch to silently pass. It also means a new contributor can read the test double and immediately understand what the function under test actually depends on.</p><h3>Protocol Composition</h3><p>Narrow protocols can be combined when a single type needs to express the full capability. With the four narrow protocols already defined, you can compose them at system boundaries such as factory functions or plugin registries.</p><pre>class FullDataSource(Loadable, Saveable, Validatable, Previewable, Protocol):<br>    pass</pre><p>FullDataSource composes the four narrow protocols via multiple inheritance. Any class that satisfies all four narrow protocols automatically satisfies FullDataSource. Use this where the complete contract matters. For individual callers, keep using the narrow protocols.</p><h3>Gotchas and Tradeoffs</h3><p>runtime_checkable checks names, not signatures. If you decorate a protocol with @runtime_checkable, isinstance(obj, Loadable) will return True if obj has a load attribute. It will not verify that load accepts no arguments and returns a DataFrame. The following standalone example illustrates why this matters.</p><pre>from typing import Protocol, runtime_checkable<br>import pandas as pd<br><br><br>@runtime_checkable<br>class Loadable(Protocol):<br>    def load(self) -&gt; pd.DataFrame: ...<br><br><br>class Broken:<br>    def load(self, extra_arg: str) -&gt; str:   # wrong signature<br>        return &quot;not a dataframe&quot;<br><br><br>print(isinstance(Broken(), Loadable))  # True — runtime check is shallow</pre><p>Do not use isinstance checks with protocols as a substitute for type annotations. Use them only for narrowing at runtime boundaries where you cannot control the input type.</p><p>Do not split if every caller uses all methods. If you have one caller that uses validate, schema, preview, and count together in a single function, splitting them into four protocols adds indirection without removing coupling. The heuristic is: one caller, one protocol. When a caller uses three methods together on every call path, those three methods belong in one protocol.</p><p>Protocol inheritance in mypy requires Protocol in every base. When composing protocols, every class in the chain must explicitly inherit from Protocol. Omitting it causes mypy to treat the class as a concrete type, not a structural interface, and structural matching breaks.</p><pre># Wrong: Validatable is not recognized as a Protocol by mypy<br>class Validatable:<br>    def validate(self, df: pd.DataFrame) -&gt; bool: ...<br>    def schema(self) -&gt; dict[str, str]: ...<br><br># Correct<br>class Validatable(Protocol):<br>    def validate(self, df: pd.DataFrame) -&gt; bool: ...<br>    def schema(self) -&gt; dict[str, str]: ...</pre><p>TypeVar bounds interact with narrow protocols. If you write T = TypeVar(&quot;T&quot;, bound=Loadable), a function parameterized on T can only use load. If the caller later needs save as well, they need a second TypeVar or a composed protocol. Plan the TypeVar bounds around the narrowest protocol the generic function actually uses.</p><h3>Takeaways</h3><p>Most protocol designs start from the class and ask “what should this expose?” The ISP asks the opposite question: “what does each caller actually need?” The answer is usually less than you think.</p><p>Look at the largest protocol in your current codebase. Count how many methods a typical caller uses. If the answer is fewer than half the protocol’s methods, you have a candidate for splitting.</p><p>What would your test doubles look like if every function depended on exactly the methods it called?</p><p>If you found this post helpful, don’t forget to <strong>👏 clap</strong> to show your support!</p><p>I’d also love to hear your thoughts and insights on the techniques covered in this article. 💡 Feel free to share your experiences in the <strong>comments</strong> 💬.</p><figure><a href="https://medium.com/@rgr5882/subscribe"><img alt="" src="https://cdn-images-1.medium.com/max/780/1*HaafLJIgmLZMblLS4wtE3w.png" /></a></figure><h3>Connect with Me on LinkedIn!</h3><p>You can also connect with me on <a href="https://www.linkedin.com/in/ricardogarciaramirez/"><strong>LinkedIn</strong> </a>for updates on my latest posts and projects. 🌐 Let’s keep the conversation going!</p><p><em>Thousands of developers share what they’re building, learning, and discovering across our publications every month. One account connects you to our entire network of publications and communities. </em><a href="https://plainenglish.io/write-for-us"><strong><em>Explore more at plainenglish.io</em></strong><em>.</em></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8090dfcbcbc0" width="1" height="1" alt=""><hr><p><a href="https://python.plainenglish.io/the-interface-segregation-principle-for-python-protocols-8090dfcbcbc0">The Interface Segregation Principle for Python Protocols</a> was originally published in <a href="https://python.plainenglish.io/">Python in Plain English</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[When Python Isn’t Fast Enough: Building a Token-Aware RAG Chunker in Rust]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://pub.towardsai.net/when-python-isnt-fast-enough-building-a-token-aware-rag-chunker-in-rust-6d3a93069367?source=rss-93688570991c------2"><img src="https://cdn-images-1.medium.com/max/2600/1*IqFmBIRx8PbmtJOXVT4crQ.png" width="4128"></a></p><p class="medium-feed-snippet">How naive character-count splitting silently corrupts your embeddings, why Python hits a parallelism ceiling, and how a Rust extension&#x2026;</p><p class="medium-feed-link"><a href="https://pub.towardsai.net/when-python-isnt-fast-enough-building-a-token-aware-rag-chunker-in-rust-6d3a93069367?source=rss-93688570991c------2">Continue reading on Towards AI »</a></p></div>]]></description>
            <link>https://pub.towardsai.net/when-python-isnt-fast-enough-building-a-token-aware-rag-chunker-in-rust-6d3a93069367?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/6d3a93069367</guid>
            <category><![CDATA[rust]]></category>
            <category><![CDATA[chunking-strategies]]></category>
            <category><![CDATA[chunking]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[agentic-rag]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Tue, 30 Jun 2026 15:01:03 GMT</pubDate>
            <atom:updated>2026-06-30T15:01:03.397Z</atom:updated>
        </item>
        <item>
            <title><![CDATA[Fail Fast: The Defensive Programming Principle You’re Applying Backwards]]></title>
            <link>https://python.plainenglish.io/fail-fast-the-defensive-programming-principle-youre-applying-backwards-a0cb2d55fd75?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/a0cb2d55fd75</guid>
            <category><![CDATA[fail-fast]]></category>
            <category><![CDATA[defensive-programming]]></category>
            <category><![CDATA[error-handling]]></category>
            <category><![CDATA[clean-code]]></category>
            <category><![CDATA[python]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Tue, 30 Jun 2026 10:52:16 GMT</pubDate>
            <atom:updated>2026-06-30T10:52:16.305Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Returning a default value instead of raising is not defensive. It is silent corruption.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/999/1*O42naad8FTZ1T485PqswzA.png" /></figure><h3>The dashboard that was wrong for two days</h3><p>The pipeline ran at midnight. No errors. No alerts. The job completed with status SUCCESS.</p><p>Two days later, a stakeholder noticed the daily revenue figure was zero. Not low, just plain zero. The pipeline had read from a data source that was temporarily unavailable, caught the connection error, logged a warning, and returned an empty DataFrame. Downstream joins on an empty DataFrame produce empty results. The aggregation summed to zero. The dashboard updated. Everything looked correct.</p><p>The code that caused it:</p><pre>import pandas as pd<br>import logging<br><br>def load_transactions(date: str) -&gt; pd.DataFrame:<br>    try:<br>        return pd.read_sql(<br>            &quot;SELECT * FROM transactions WHERE date = %s&quot;,<br>            conn,<br>            params=[date],<br>        )<br>    except Exception as e:<br>        logging.warning(f&quot;Failed to load transactions: {e}&quot;)<br>        return pd.DataFrame()  # &quot;safe&quot; fallback</pre><p>The function returned a result. The result was wrong. The caller had no way to know.</p><p>By the end of this article, you will understand why returning a default on failure is almost always the wrong choice, what to do instead, and how to apply the fail-fast principle correctly at each layer of a system.</p><h3>What fail-fast actually means</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1004/1*ClPqGd1hO-3B1S_VZtU3hg.png" /></figure><p>Fail-fast is the principle that a program should stop and report an error as soon as it detects an invalid state, rather than continuing with potentially corrupted data.</p><p>The key word is <em>immediately</em>. Not at the end of the pipeline. Not when a user notices. At the point where the invalid state first appears.</p><p>This is the opposite of what most engineers mean when they write “defensive” code. Returning 0 when a value is None, swallowing a connection error and returning an empty result, catching Exception and logging a warning…these feel safe until they are not. They keep the program running. But they move the failure from the origin to a distant consequence, where it will be much harder to diagnose.</p><p><strong>The test:</strong> if your function returns a valid-looking result when something went wrong, that function has hidden a bug.</p><h3>Anti-pattern 1: The sentinel return</h3><pre>import re<br><br># BAD — None is indistinguishable from &quot;not found&quot; vs &quot;error&quot;<br>def extract_user_id(text: str):<br>    match = re.search(r&quot;user_id=(\d+)&quot;, text)<br>    if match:<br>        return int(match.group(1))<br>    return None  # was this &quot;not found&quot; or &quot;pattern broke&quot;?<br><br><br># Caller has no way to distinguish the two failure modes<br>user_id = extract_user_id(log_line)<br>if user_id:<br>    process(user_id)<br># else: silently skipped</pre><p>Returning None on failure forces every caller to write if result is not None and hope they remember to do so. Raising forces the caller to make an explicit decision.</p><pre>import re<br><br># BETTER — raise when the function&#39;s contract is violated<br>def extract_user_id(text: str) -&gt; int:<br>    match = re.search(r&quot;user_id=(\d+)&quot;, text)<br>    if not match:<br>        raise ValueError(f&quot;No user_id found in: {text!r}&quot;)<br>    return int(match.group(1))<br><br><br># Now the caller must make a conscious decision<br>try:<br>    user_id = extract_user_id(log_line)<br>except ValueError as e:<br>    logger.error(&quot;Malformed log line, skipping: %s&quot;, e)<br>    raise  # or handle explicitly — not silently</pre><p>Raising makes the contract legible from the signature: -&gt; int means this function always returns an integer on success. Callers cannot ignore the failure path, so they must write an explicit try/except or let the exception propagate to a layer that can handle it. The ambiguity between “not found” and “error” is gone.</p><h3>Anti-pattern 2: Exception swallowing</h3><pre>import json<br><br># BAD — the exception disappears<br>def parse_config(path: str) -&gt; dict:<br>    try:<br>        with open(path) as f:<br>            return json.load(f)<br>    except Exception:<br>        return {}  # caller gets an empty dict, assumes config loaded<br><br><br>config = parse_config(&quot;config.json&quot;)<br>timeout = config.get(&quot;timeout&quot;, 30)  # silently gets the default<br># the application runs with wrong configuration and no one knows</pre><p>except Exception: return {} converts every possible failure: file not found, permission denied, disk full, malformed UTF-8, truncated JSON, into the same silent empty dictionary. The caller receives a valid-looking result and falls back to defaults, with no indication that the config was never read. The application runs with wrong settings and nothing in the output explains why.</p><pre>import json<br>from pathlib import Path<br><br># BETTER — fail at the boundary, clearly<br>def parse_config(path: str) -&gt; dict:<br>    config_path = Path(path)<br>    if not config_path.exists():<br>        raise FileNotFoundError(f&quot;Config file not found: {path}&quot;)<br>    try:<br>        return json.loads(config_path.read_text(encoding=&quot;utf-8&quot;))<br>    except json.JSONDecodeError as e:<br>        raise ValueError(f&quot;Config file is not valid JSON: {path}&quot;) from e<br><br><br># Now the caller knows immediately, not three function calls later</pre><p>Catching only the specific exceptions that can realistically occur and re-raising with context keeps each failure diagnosable: was the file missing, or was it corrupted? The from e clause chains the original exception so the traceback shows both the root cause and the higher-level error. The caller gets a clear signal, not a silent empty dict, and can decide whether to abort, retry, or alert.</p><h3>Anti-pattern 3: Defensive defaults that corrupt results</h3><pre>import statistics<br><br># BAD — returns 0 when it should signal &quot;no data&quot;<br>def mean_response_time(times: list) -&gt; float:<br>    if not times:<br>        return 0.0  # &quot;safe&quot; but wrong: 0ms is a valid-looking result<br><br><br># One bucket with no data pulls the aggregate down.<br># The metric looks slightly low. No one investigates.</pre><p>Returning 0.0 for an empty input makes absence of data indistinguishable from a genuine zero mean. If this value flows into an aggregate, the average of multiple time buckets, for example, one empty bucket silently pulls the total down. The metric is wrong, nothing signals that it is wrong, and the problem can persist for days before someone investigates a “slightly low” number.</p><pre>import statistics<br><br># BETTER — raise when the contract is violated<br>def mean_response_time(times: list) -&gt; float:<br>    if not times:<br>        raise ValueError(&quot;Cannot compute mean of empty sequence&quot;)<br>    return statistics.mean(times)<br><br><br># Now empty buckets surface as errors instead of silent zeros</pre><p>Raising on an empty sequence transfers the decision to the caller, where it belongs. The caller can skip the bucket, log a warning, substitute None, or halt the pipeline; but that choice is now explicit and visible in code. No data is more honest than wrong data that looks correct.</p><h3>Where to actually catch exceptions</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1006/1*5s5qaK82oPrSXhrqL02Rjw.png" /></figure><p>Fail-fast does not mean “never catch exceptions.” It means catch only what you can meaningfully handle, at the layer where meaningful handling is possible.</p><p>The correct layers:</p><p><strong>System entry points: </strong>CLI main, API endpoint handlers, Celery task wrappers. These are the boundaries where you convert internal exceptions into user-facing messages or structured error responses. Catch broadly here, convert to appropriate output, and log.</p><pre># API endpoint — system boundary<br>@app.route(&quot;/train&quot;, methods=[&quot;POST&quot;])<br>def train_endpoint():<br>    try:<br>        result = run_training_pipeline(request.json)<br>        return jsonify(result)<br>    except ValueError as e:<br>        return jsonify({&quot;error&quot;: str(e)}), 400<br>    except Exception as e:<br>        logger.exception(&quot;Unexpected error in /train&quot;)<br>        return jsonify({&quot;error&quot;: &quot;Internal error&quot;}), 500</pre><p><strong>Internal functions: </strong>do not catch. Let exceptions propagate. The function that detects a problem is rarely the function that can fix it.</p><pre># Internal helper — raises; never catches<br>def load_user_profile(user_id: int) -&gt; dict:<br>    row = db.query(&quot;SELECT * FROM users WHERE id = %s&quot;, [user_id])<br>    if row is None:<br>        raise ValueError(f&quot;User {user_id} not found&quot;)<br>    return row<br># Boundary — the only place that catches and converts to a response<br>@app.route(&quot;/profile/&lt;int:user_id&gt;&quot;)<br>def profile_endpoint(user_id: int):<br>    try:<br>        profile = load_user_profile(user_id)<br>        return jsonify(profile)<br>    except ValueError as e:<br>        return jsonify({&quot;error&quot;: str(e)}), 404<br>    except Exception as e:<br>        logger.exception(&quot;Unexpected error fetching profile %d&quot;, user_id)<br>        return jsonify({&quot;error&quot;: &quot;Internal error&quot;}), 500</pre><p><strong>Retry logic: </strong>catch specific, transient exceptions (network timeouts, rate limits) and retry. Do not catch Exception,that catches logic errors too.</p><pre>import requests<br>import time<br><br>def fetch_with_retry(url: str, max_retries: int = 3) -&gt; bytes:<br>    for attempt in range(max_retries):<br>        try:<br>            return requests.get(url, timeout=10).content<br>        except requests.Timeout:<br>            # Catching Timeout only — specific, transient; NOT catching Exception<br>            if attempt == max_retries - 1:<br>                raise<br>            time.sleep(2 ** attempt)</pre><h3>Validation at function boundaries</h3><p>For functions that accept external data (user input, file contents, API responses), validate inputs at the top of the function before doing any work:</p><pre>from __future__ import annotations<br>from dataclasses import dataclass<br><br><br>@dataclass<br>class TrainingConfig:<br>    learning_rate: float<br>    epochs: int<br>    model_path: str<br><br><br>def validate_training_config(config: TrainingConfig) -&gt; None:<br>    if config.learning_rate &lt;= 0 or config.learning_rate &gt; 1:<br>        raise ValueError(f&quot;learning_rate must be in (0, 1], got {config.learning_rate}&quot;)<br>    if config.epochs &lt; 1:<br>        raise ValueError(f&quot;epochs must be &gt;= 1, got {config.epochs}&quot;)<br>    if not config.model_path:<br>        raise ValueError(&quot;model_path cannot be empty&quot;)<br><br><br>def run_training(config: TrainingConfig) -&gt; None:<br>    validate_training_config(config)  # fail at the top, before any work<br>    # ... training logic</pre><p>This is preferable to discovering a bad value in the middle of a two-hour training job.</p><h3>Takeaways</h3><ul><li>Returning a default on failure hides bugs. A crash with a clear message is safer than a corrupted result that looks correct.</li><li>Catch exceptions only at system boundaries (API handlers, CLI main, task runners) and in explicit retry logic for transient failures.</li><li>Internal functions should raise, not return sentinels, and not swallow exceptions.</li><li>Validate inputs at the top of a function before doing any work.</li><li>assert for development-time invariants; raise ValueError for production input validation.</li></ul><p>The other half of this principle, what to do when you <em>do</em> need to catch, will be in <em>Stop Catching Every Exception </em>as a follow-up article.</p><p>If you found this post helpful, don’t forget to <strong>👏 clap</strong> to show your support!</p><p>I’d also love to hear your thoughts and insights on the techniques covered in this article. 💡 Feel free to share your experiences in the <strong>comments</strong> 💬.</p><figure><a href="https://medium.com/@rgr5882/subscribe"><img alt="" src="https://cdn-images-1.medium.com/max/780/1*HaafLJIgmLZMblLS4wtE3w.png" /></a></figure><h3>Connect with Me on LinkedIn!</h3><p>You can also connect with me on <a href="https://www.linkedin.com/in/ricardogarciaramirez/"><strong>LinkedIn</strong> </a>for updates on my latest posts and projects. 🌐 Let’s keep the conversation going!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a0cb2d55fd75" width="1" height="1" alt=""><hr><p><a href="https://python.plainenglish.io/fail-fast-the-defensive-programming-principle-youre-applying-backwards-a0cb2d55fd75">Fail Fast: The Defensive Programming Principle You’re Applying Backwards</a> was originally published in <a href="https://python.plainenglish.io/">Python in Plain English</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Stop Using requirements.txt for Your Projects]]></title>
            <link>https://levelup.gitconnected.com/stop-using-requirements-txt-for-your-projects-059680879714?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/059680879714</guid>
            <category><![CDATA[requirements]]></category>
            <category><![CDATA[ci-cd-pipeline]]></category>
            <category><![CDATA[clean-code]]></category>
            <category><![CDATA[coding-best-practices]]></category>
            <category><![CDATA[python]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Mon, 29 Jun 2026 19:42:51 GMT</pubDate>
            <atom:updated>2026-06-29T19:42:51.652Z</atom:updated>
            <content:encoded><![CDATA[<p>It’s not a dependency management tool. It’s a deployment artifact, and using it as the former creates problems the latter is not designed to solve.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*onrERGrsCgChBT6mDVEQEQ.png" /></figure><h3>The CI pipeline that breaks</h3><p>Nobody changed any code over the weekend. On Monday morning, the CI pipeline failed. The error was in a test that had been passing for six months:</p><pre>ImportError: cannot import name &#39;DEFAULT_RETRIES&#39; from &#39;urllib3&#39;</pre><p>The requirements.txt had:</p><pre>requests<br>pandas<br>scikit-learn</pre><p>No version pins. urllib3 is a transitive dependency of requests. A new major version had released on Saturday with a breaking API change. pip install installed it. The code broke.</p><p>This is not an unusual story. If your requirements.txt has unpinned dependencies, every pip install is a roll of the dice.</p><p>By the end of this article, you will know why requirements.txt is the wrong tool for dependency specification, what to use instead, and how to migrate in under ten minutes.</p><h3>What requirements.txt was designed for</h3><p>requirements.txt is a pip installation manifest. It tells pip what to install. That’s all.</p><p>It was not designed to:</p><ul><li>Resolve dependency conflicts before install</li><li>Separate top-level dependencies from transitive dependencies</li><li>Separate development dependencies from production dependencies</li><li>Guarantee reproducibility across machines and time</li></ul><p>When you write requirements.txt as your <em>source of truth</em> for project dependencies, you are using a deployment artifact as a design document. The analogy: writing your database schema by reverse-engineering a SQL dump rather than maintaining a migration file. Both approaches get you the same data today. Neither tells you how it got there.</p><h3>The three problems</h3><ol><li><strong>No reproducibility guarantee</strong></li></ol><pre># requirements.txt — what you write<br>requests<br>pandas&gt;=1.5<br>scikit-learn==1.2.2</pre><p>This file will install different versions of requests and pandas on your laptop, in CI, and in production. scikit-learn is pinned, but requests is not, and requests depends on certifi, charset-normalizer, idna, and urllib3 — none of which are specified here.</p><p>A fully pinned requirements.txt helps:</p><pre># requirements.txt — fully pinned<br>requests==2.31.0<br>certifi==2024.2.2<br>charset-normalizer==3.3.2<br>idna==3.7<br>urllib3==2.2.1<br>pandas==2.2.1<br>...</pre><p>But now you have a new problem: which of these did you actually add, and which appeared because they’re transitive? When a security advisory requires updating certifi, do you know which of your direct dependencies pulls it in?</p><p><strong>2. No separation between dev and production</strong></p><pre># requirements.txt — everything mixed together<br>flask==3.0.0<br>sqlalchemy==2.0.28<br>pytest==8.1.0          # dev only<br>black==24.3.0           # dev only<br>mypy==1.9.0             # dev only<br>coverage==7.4.4         # dev only</pre><p>Your production container installs pytest and mypy. Nobody intended this. The container is larger, slower to build, and has a broader attack surface. Separating these requires manually managing two or more files (requirements.txt, requirements-dev.txt) with no tooling enforcing the boundary.</p><p><strong>3. No conflict detection before install</strong></p><p>pip will attempt to install what you specify and fail mid-install if there’s a conflict. There is no pre-install dependency resolution that tells you <em>before</em> you start that packageA==1.0 and packageB==2.0 require incompatible versions of packageC.</p><h3>The modern alternative: pyproject.toml + uv</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*C9w_-muA9yoLG4Sui2allg.png" /></figure><p>pyproject.toml is the PEP 517/518/621 standard for Python project metadata, build configuration, and dependency specification. uv is a fast, modern package manager from the team behind ruff. Together they replace both requirements.txt and pip.</p><p><strong>Step 1: Specify direct dependencies in pyproject.toml</strong></p><pre># pyproject.toml<br>[project]<br>name = &quot;my-project&quot;<br>version = &quot;0.1.0&quot;<br>requires-python = &quot;&gt;=3.11&quot;<br>dependencies = [<br>    &quot;requests&gt;=2.31&quot;,<br>    &quot;pandas&gt;=2.0&quot;,<br>    &quot;scikit-learn&gt;=1.2&quot;,<br>]<br><br>[project.optional-dependencies]<br>dev = [<br>    &quot;pytest&gt;=8.0&quot;,<br>    &quot;black&gt;=24.0&quot;,<br>    &quot;mypy&gt;=1.0&quot;,<br>]</pre><p>This is the <em>abstract</em> specification: your direct dependencies with minimum versions. It does not pin transitive deps. It does not belong in the lockfile.</p><p>Note: if you are using uv ≥ 0.4, the newer [dependency-groups] syntax (PEP 735) is also supported and offers additional features. [project.optional-dependencies] is shown here because it is supported by all tools, not just uv.</p><p><strong>Step 2: Generate a lockfile</strong></p><pre># Install uv (one-time)<br>pip install uv<br><br># Generate uv.lock — pins every dependency transitively with hashes<br>uv lock<br><br># Install from lockfile (reproducible on any machine)<br>uv sync</pre><p>The uv.lock file is what you commit to source control. It pins every direct and transitive dependency to an exact version with a hash. uv sync always installs exactly what the lockfile says so there are no surprises.</p><pre># Install production deps only (excludes dev group)<br>uv sync --no-dev<br><br># Install everything including dev group<br>uv sync --extra dev</pre><h3>Step 3: Add a dependency</h3><pre># Add requests — updates pyproject.toml and regenerates uv.lock atomically<br>uv add requests<br><br># Add a dev dependency<br>uv add --optional dev pytest</pre><p>The workflow is: edit pyproject.toml for the abstract spec, commit uv.lock for reproducibility, use uv sync everywhere.</p><h3>If you can’t switch to uv yet</h3><p>If your team or organisation is not ready to adopt uv, the pip-compile approach provides the same abstract-spec + lockfile separation using only pip:</p><pre>pip install pip-tools<br><br># pyproject.toml has your abstract deps — generate a lockfile:<br>pip-compile pyproject.toml -o requirements.lock<br><br># Install from lockfile:<br>pip install -r requirements.lock</pre><p>Keep pyproject.toml as your source of truth. Use requirements.lock (not requirements.txt) as your pinned artifact. The naming matters: requirements.lock is clearly a generated file, not something you edit by hand.</p><h3>Migration path from requirements.txt</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XHlwoqsuMXzl9fbpS7519A.png" /></figure><p>If you have an existing project with requirements.txt:</p><ol><li>Create pyproject.toml with [project.dependencies] listing only your direct dependencies (the ones you actually import).</li><li>Run uv lock to generate uv.lock with all transitive deps pinned.</li><li>Delete requirements.txt or rename it to requirements.txt.bak to avoid confusion.</li><li>Update CI to run uv sync instead of pip install -r requirements.txt.</li></ol><p>The only question is identifying which of your requirements.txt entries are direct dependencies versus transitive. Use pipdeptree to find out:</p><pre>pip install pipdeptree<br>pipdeptree --warn silence | grep -v &quot;  &quot;  # shows only top-level packages</pre><h3>Gotchas</h3><p>uv.lock is not meant to be edited by hand. Run uv lock to regenerate it. If you see merge conflicts in uv.lock, regenerate rather than resolving manually.</p><p>Applications commit the lockfile; libraries don’t. Data pipelines, web apps, and batch jobs are applications; commit uv.lock. If you’re writing a pip-installable library meant to be used as a dependency by others, commit pyproject.toml only and let each consumer’s resolver handle exact pinning.</p><h3>Takeaways</h3><ul><li>requirements.txt with unpinned dependencies is a reproducibility hazard. Every pip install is a new resolution.</li><li>requirements.txt with fully pinned dependencies is better but doesn’t separate direct from transitive, or dev from prod.</li><li>pyproject.toml is the standard for abstract dependency specification. uv.lock (or requirements.lock via pip-compile) is the reproducible artefact you commit.</li><li>uv sync installs exactly what the lockfile says. No surprises in CI, staging, or production.</li></ul><p>If you found this post helpful, don’t forget to <strong>👏 clap</strong> to show your support!</p><p>I’d also love to hear your thoughts and insights on the techniques covered in this article. 💡 Feel free to share your experiences in the <strong>comments</strong> 💬.</p><figure><a href="https://medium.com/@rgr5882/subscribe"><img alt="" src="https://cdn-images-1.medium.com/max/780/1*HaafLJIgmLZMblLS4wtE3w.png" /></a></figure><h3>Connect with Me on LinkedIn!</h3><p>You can also connect with me on <a href="https://www.linkedin.com/in/ricardogarciaramirez/"><strong>LinkedIn</strong> </a>for updates on my latest posts and projects. 🌐 Let’s keep the conversation going!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=059680879714" width="1" height="1" alt=""><hr><p><a href="https://levelup.gitconnected.com/stop-using-requirements-txt-for-your-projects-059680879714">Stop Using requirements.txt for Your Projects</a> was originally published in <a href="https://levelup.gitconnected.com/">Level Up Coding</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Python Type Hints: Beyond Basic Annotations]]></title>
            <link>https://blog.devgenius.io/python-type-hints-beyond-basic-annotations-516724ec834b?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/516724ec834b</guid>
            <category><![CDATA[typing]]></category>
            <category><![CDATA[type-hints]]></category>
            <category><![CDATA[python]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Sat, 27 Jun 2026 20:41:00 GMT</pubDate>
            <atom:updated>2026-06-27T20:41:00.786Z</atom:updated>
            <content:encoded><![CDATA[<p><em>str, int, and list are just the start: here are the type tools that do real work.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bexpz4Ul66nV-cHEa07WdQ.png" /></figure><h4>The annotation that didn’t help</h4><pre>def first(items: list) -&gt; object:<br>    return items[0]<br><br>nums = [1, 2, 3]<br>result = first(nums)<br># mypy doesn&#39;t know result is int — it&#39;s typed as object<br># result + 1 # mypy error: unsupported operand type</pre><p>list without a type parameter loses the element type. mypy infers result as object, not int. The annotation described “a list” — it said nothing about what the list contains or what the function returns.</p><p>The five tools in this article enforce <em>contracts</em>: relationships between types, structural requirements, constrained values. They move type hints from documentation into enforcement.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dRi5bx42xeQaXOSKvJCppg.png" /></figure><h4>1. TypeVar — preserve the relationship between input and output</h4><pre>from typing import TypeVar, Sequence<br><br>T = TypeVar(&quot;T&quot;)<br><br>def first(items: Sequence[T]) -&gt; T:<br>    return items[0]<br><br>x: int = first([1, 2, 3])       # mypy: x is int ✓<br>s: str = first([&quot;a&quot;, &quot;b&quot;, &quot;c&quot;]) # mypy: s is str ✓<br>print(x, s)</pre><pre>1 a</pre><p>T is a type variable — it captures the element type of the input and carries it to the output. mypy now knows that first([1, 2, 3]) returns int, not object.</p><p>Constrain TypeVar to specific types when the function only works for some:</p><pre>from typing import TypeVar<br><br>Numeric = TypeVar(&quot;Numeric&quot;, int, float)<br><br>def double(x: Numeric) -&gt; Numeric:<br>    return x * 2<br><br>print(double(3))    # 6<br>print(double(2.5))  # 5.0<br># double(&quot;hello&quot;) # mypy error: str is not int or float</pre><pre>6<br>5.0</pre><h4>2. Protocol — structural typing without inheritance</h4><pre>from typing import Protocol<br><br>class Closeable(Protocol):<br>    def close(self) -&gt; None: ...<br><br>def shutdown(resource: Closeable) -&gt; None:<br>    resource.close()<br>    print(&quot;closed&quot;)<br><br>class DatabaseConnection:<br>    def close(self) -&gt; None:<br>        print(&quot;DB connection closed&quot;)<br><br>class FileHandle:<br>    def close(self) -&gt; None:<br>        print(&quot;File handle closed&quot;)<br><br>shutdown(DatabaseConnection())<br>shutdown(FileHandle())</pre><pre>DB connection closed<br>closed<br>File handle closed<br>closed</pre><p>Neither DatabaseConnection nor FileHandle inherits from Closeable. They satisfy it <em>structurally, </em>mypy checks that they have the required methods. This is the right tool for third-party objects you can’t modify.</p><h4>3. Literal — constrain to a fixed set of values</h4><pre>from typing import Literal<br><br>def set_log_level(level: Literal[&quot;DEBUG&quot;, &quot;INFO&quot;, &quot;WARNING&quot;, &quot;ERROR&quot;]) -&gt; None:<br>    print(f&quot;Log level set to: {level}&quot;)<br><br>set_log_level(&quot;INFO&quot;)<br># set_log_level(&quot;VERBOSE&quot;) # mypy error: not a valid Literal value</pre><pre>Log level set to: INFO</pre><p>level: str accepts anything. level: Literal[...] restricts to the listed values and mypy rejects anything else at type-check time — before the code runs.</p><h4>4. TypedDict — type-checked dictionaries</h4><pre>from typing import TypedDict<br><br>class UserRecord(TypedDict):<br>    id: int<br>    name: str<br>    email: str<br><br>def format_user(user: UserRecord) -&gt; str:<br>    return f&quot;{user[&#39;name&#39;]} &lt;{user[&#39;email&#39;]}&gt;&quot;<br><br>user: UserRecord = {&quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;, &quot;email&quot;: &quot;alice@example.com&quot;}<br>print(format_user(user))<br># user[&quot;phone&quot;] # mypy error: key doesn&#39;t exist</pre><pre>Alice &lt;alice@example.com&gt;</pre><p>mypy checks that required keys exist and have the right types. total=False makes all keys optional:</p><pre>from typing import TypedDict<br><br>class Config(TypedDict, total=False):<br>    debug: bool<br>    log_level: str<br>    timeout: int<br><br>config: Config = {&quot;debug&quot;: True}<br>print(config)</pre><pre>{&#39;debug&#39;: True}</pre><h4>5. overload — multiple signatures for the same function</h4><p>@overload narrows the return type based on the input type. Union[A, B] means the value can be either type — without @overload, mypy can’t narrow which one applies to a specific call.</p><pre>from typing import overload, Union<br><br>@overload<br>def process(value: int) -&gt; str: ...<br>@overload<br>def process(value: str) -&gt; int: ...<br><br>def process(value: Union[int, str]) -&gt; Union[str, int]:<br>    if isinstance(value, int):<br>        return str(value)<br>    return len(value)<br><br>result_a: str = process(42)       # mypy: str ✓<br>result_b: int = process(&quot;hello&quot;)  # mypy: int ✓<br>print(result_a, result_b)</pre><pre>42 5</pre><p>Without @overload, both calls return Union[str, int] and the result_a: str annotation would fail mypy. With it, mypy narrows the return type per call.</p><h4>Takeaways</h4><ul><li>Basic annotations describe shape. These five tools enforce contracts.</li><li>TypeVar preserves the type relationship between input and output in generic functions.</li><li>Protocol enables structural typing — “anything with this method” — without inheritance.</li><li>Literal catches invalid constant-string arguments at type-check time.</li><li>TypedDict makes dictionary structure explicit and checkable at API boundaries.</li><li>@overload gives callers precise return-type information when a function is polymorphic.</li></ul><p>If you found this post helpful, don’t forget to <strong>👏 clap</strong> to show your support!</p><p>I’d also love to hear your thoughts and insights on the techniques covered in this article. 💡 Feel free to share your experiences in the <strong>comments</strong> 💬.</p><figure><a href="https://medium.com/@rgr5882/subscribe"><img alt="" src="https://cdn-images-1.medium.com/max/780/1*HaafLJIgmLZMblLS4wtE3w.png" /></a></figure><h3>Connect with Me on LinkedIn!</h3><p>You can also connect with me on <a href="https://www.linkedin.com/in/ricardogarciaramirez/"><strong>LinkedIn</strong> </a>for updates on my latest posts and projects. 🌐 Let’s keep the conversation going!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=516724ec834b" width="1" height="1" alt=""><hr><p><a href="https://blog.devgenius.io/python-type-hints-beyond-basic-annotations-516724ec834b">Python Type Hints: Beyond Basic Annotations</a> was originally published in <a href="https://blog.devgenius.io/">Dev Genius</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your Configuration Is Hardcoded in Disguise]]></title>
            <link>https://python.plainenglish.io/your-configuration-is-hardcoded-in-disguise-ad2ba7be4aeb?source=rss-93688570991c------2</link>
            <guid isPermaLink="false">https://medium.com/p/ad2ba7be4aeb</guid>
            <category><![CDATA[pydantic]]></category>
            <category><![CDATA[python-dataclass]]></category>
            <category><![CDATA[configuration-management]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[clean-code]]></category>
            <dc:creator><![CDATA[Ricardo García Ramírez]]></dc:creator>
            <pubDate>Wed, 24 Jun 2026 16:44:02 GMT</pubDate>
            <atom:updated>2026-06-24T16:44:02.819Z</atom:updated>
            <content:encoded><![CDATA[<p><em>A constant at the top of a file is still hardcoded, same for a config.py. Here’s what to do instead.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GW0ktFYK8b5YszYUmlrzZA.png" /></figure><h3>The staging deploy</h3><p>You deploy to staging. The model fails to load. You grep the codebase:</p><pre># config.py<br>MODEL_PATH = &quot;/models/v2&quot;<br>DB_HOST = &quot;localhost&quot;<br>MAX_RETRIES = 3</pre><p>Staging has v3. You change MODEL_PATH = &quot;/models/v3&quot;, redeploy. It works. Two weeks later production needs v4. Same fix, same deploy. You have a config.py but you do not have a configuration … you have hardcoding you can find quickly.</p><p>By the end of this article, you will have a clear test for what counts as configuration, three correct places to put it, and a startup validation pattern that turns misconfiguration into a loud error rather than a silent runtime mystery.</p><h3>What configuration actually is</h3><p>Configuration is anything that changes between environments, runs, or deployments without requiring a code change or redeploy.</p><p>Apply the test:</p><ul><li>DB_HOST = &quot;localhost&quot; changes between dev/staging/prod? Yes → configuration.</li><li>MODEL_PATH = &quot;/models/v2&quot; changes when a new model is deployed? Yes → configuration.</li><li>MAX_RETRIES = 3 a policy decision that might be adjusted per deployment? Probably configuration.</li><li>BATCH_SIZE = 32 a tuning parameter that varies per run? Configuration (CLI arg). Never changes after the initial decision? Constant: fine in code.</li></ul><p>Constants are decisions made once in the codebase. Configuration is decisions made outside the codebase, per deployment or per run, they are more about the environment you are setting them in. It’s not the same running a pod, a container, or testing on local.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hbecUrSwrpMz_BH_6FPcwA.png" /></figure><h3>Three anti-patterns</h3><p><strong>Python file as config</strong>: requires a code change to update, commits secrets to source control, cannot be overridden per environment (and probably a crawler will pick it up, please don’t use this one):</p><pre># config.py this is NOT configuration<br>API_KEY = &quot;sk-hardcoded-secret-key&quot;  # committed to git<br>MODEL_PATH = &quot;/models/v2&quot;            # requires redeploy to change</pre><p><strong>Magic strings scattered across modules,</strong> no single place to audit or change:</p><pre># pipeline.py<br>def load_model():<br>    return load(&quot;/models/v2/classifier.pkl&quot;)  # grep-only discoverability</pre><p><strong>Config mixed with logic</strong>: entangles environment decisions with business logic, makes testing require env var setup:</p><pre>def connect():<br>    host = &quot;db.prod.example.com&quot; if os.environ.get(&quot;ENV&quot;) == &quot;prod&quot; else &quot;localhost&quot;<br>    return psycopg2.connect(host=host)</pre><p>The antipatterns show that making changes becomes hardcoding you can find quickly, but they don’t let you mix and match configurations properly into different environments easily. Next, we have what to do instead.</p><h3>The three correct homes</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4wO45SrkeQcwQ11mYx8r7g.png" /></figure><h4>Environment variables: secrets and environment-specific values</h4><pre>import os<br><br>db_host = os.environ[&quot;DB_HOST&quot;]                           # required — raises KeyError if missing<br>api_key = os.environ[&quot;API_KEY&quot;]<br>model_path = os.environ.get(&quot;MODEL_PATH&quot;, &quot;/models/default&quot;)  # optional with default<br><br># Set for demonstration:<br>os.environ[&quot;DB_HOST&quot;] = &quot;db.staging.example.com&quot;<br>os.environ[&quot;API_KEY&quot;] = &quot;test-key&quot;<br><br>print(os.environ[&quot;DB_HOST&quot;])<br>print(os.environ.get(&quot;TIMEOUT&quot;, &quot;30&quot;))</pre><p>Use os.environ[&quot;KEY&quot;] for required values (raises KeyError immediately if missing) and os.environ.get(&quot;KEY&quot;, default) for optional ones.</p><h4>Config files: structured settings that vary between deployments</h4><pre>import yaml<br><br># In production, read from a file: yaml.safe_load(Path(&quot;config.yaml&quot;).read_text())<br># Here we use an inline string for demonstration:<br>config_yaml = &quot;&quot;&quot;<br>database:<br>  host: db.staging.example.com<br>  port: 5432<br>pipeline:<br>  max_retries: 3<br>  batch_size: 64<br>&quot;&quot;&quot;<br><br>config = yaml.safe_load(config_yaml)<br>print(config[&quot;database&quot;][&quot;host&quot;])<br>print(config[&quot;pipeline&quot;][&quot;max_retries&quot;])</pre><p>Config files are the right home for structured, non-secret settings. You maintain config.staging.yaml and config.prod.yaml separately, or your deployment tooling generates them. You might use toml or json , I’d even accept xml files, just keep a config file structured and the api keys out of git, those are secrets you can configure in your Cloud provider or even in GitHub.</p><h4>CLI arguments: per-run overrides</h4><pre>import argparse<br><br>parser = argparse.ArgumentParser()<br>parser.add_argument(&quot;--model-path&quot;, default=&quot;/models/default&quot;)<br>parser.add_argument(&quot;--batch-size&quot;, type=int, default=32)<br># parse_args([]) uses defaults — omit [] in production to read from sys.argv<br>args = parser.parse_args([])<br><br>print(args.model_path, args.batch_size)</pre><p>CLI arguments are the right home for per-run values: model paths for training experiments, date ranges for batch jobs, batch sizes for tuning.</p><h3>The startup validation pattern</h3><p>Configuration problems should surface at startup, not at runtime. Here’s an example:</p><pre>from __future__ import annotations<br>import os<br>from dataclasses import dataclass<br><br><br>@dataclass(frozen=True) #Notice how we are using a frozen dataclass, immutable<br>class Settings:<br>    db_host: str<br>    api_key: str<br>    model_path: str<br>    max_retries: int<br><br>    @classmethod<br>    def from_env(cls) -&gt; &quot;Settings&quot;:<br>        missing = [k for k in (&quot;DB_HOST&quot;, &quot;API_KEY&quot;, &quot;MODEL_PATH&quot;) if not os.environ.get(k)]<br>        if missing:<br>            raise EnvironmentError(f&quot;Missing required env vars: {&#39;, &#39;.join(missing)}&quot;)<br>        return cls(<br>            db_host=os.environ[&quot;DB_HOST&quot;],<br>            api_key=os.environ[&quot;API_KEY&quot;],<br>            model_path=os.environ[&quot;MODEL_PATH&quot;],<br>            max_retries=int(os.environ.get(&quot;MAX_RETRIES&quot;, &quot;3&quot;)),<br>        )<br><br><br>os.environ.update({&quot;DB_HOST&quot;: &quot;localhost&quot;, &quot;API_KEY&quot;: &quot;key&quot;, &quot;MODEL_PATH&quot;: &quot;/models/v3&quot;})<br>settings = Settings.from_env()<br>print(settings.db_host, settings.model_path, settings.max_retries)</pre><p>If any required variable is missing, from_env() raises EnvironmentError immediately, and the application does not start. frozen=True prevents mutation after loading.</p><p>For larger projects, pydantic-settings provides the same pattern with automatic type coercion, .env file support, and field validation. The dataclass version above is the zero-dependency equivalent.</p><h3>Gotchas</h3><p><strong>Don’t over-configure. </strong>A value that never changes after the initial decision is a constant. Putting it in environment variables adds complexity without benefit.</p><p><strong>.env files are for <em>local development</em> only.</strong> python-dotenv loads .env into environment variables for local dev. In production, use your deployment platform’s native secrets management, please, please, please, don’t check .env into source control (a crawler will get your api keys, believe me).</p><p><strong>Validate types at load time.</strong> os.environ returns strings. Convert and validate at startup: int(os.environ[&quot;MAX_RETRIES&quot;]). A ValueError at startup beats a TypeError deep in a batch job.</p><h3>Takeaways</h3><ul><li>Configuration is anything that changes between environments or runs without a code change. Constants in Python files are hardcoding, which is an anti-pattern.</li><li>Load and validate all configuration at startup. A loud startup error beats a silent runtime failure.</li><li>frozen=True on a settings dataclass prevents accidental mutation after startup, or use Pydantic; it’s actually pretty cool once you get the hang of it.</li></ul><p>If you found this post helpful, don’t forget to <strong>👏 clap</strong> to show your support!</p><p>I’d also love to hear your thoughts and insights on the techniques covered in this article. 💡 Feel free to share your experiences in the <strong>comments</strong> 💬.</p><figure><a href="https://medium.com/@rgr5882/subscribe"><img alt="" src="https://cdn-images-1.medium.com/max/780/1*HaafLJIgmLZMblLS4wtE3w.png" /></a></figure><h3>Connect with Me on LinkedIn!</h3><p>You can also connect with me on <a href="https://www.linkedin.com/in/ricardogarciaramirez/"><strong>LinkedIn</strong> </a>for updates on my latest posts and projects. 🌐 Let’s keep the conversation going!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ad2ba7be4aeb" width="1" height="1" alt=""><hr><p><a href="https://python.plainenglish.io/your-configuration-is-hardcoded-in-disguise-ad2ba7be4aeb">Your Configuration Is Hardcoded in Disguise</a> was originally published in <a href="https://python.plainenglish.io/">Python in Plain English</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>