<?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 Sergey Kovalchuk on Medium]]></title>
        <description><![CDATA[Stories by Sergey Kovalchuk on Medium]]></description>
        <link>https://medium.com/@progsly?source=rss-94fbaaa88f------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*wViSZHZerEZqMrAf</url>
            <title>Stories by Sergey Kovalchuk on Medium</title>
            <link>https://medium.com/@progsly?source=rss-94fbaaa88f------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 09:29:40 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@progsly/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[Stop Sending Bug Reports Like “It Doesn’t Work”]]></title>
            <link>https://medium.com/@progsly/stop-sending-bug-reports-like-it-doesnt-work-da238c9c4feb?source=rss-94fbaaa88f------2</link>
            <guid isPermaLink="false">https://medium.com/p/da238c9c4feb</guid>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[startup]]></category>
            <dc:creator><![CDATA[Sergey Kovalchuk]]></dc:creator>
            <pubDate>Wed, 17 Jun 2026 08:46:05 GMT</pubDate>
            <atom:updated>2026-06-17T08:46:05.782Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3NRe_G8rT8ujRcmml_rh3w.png" /></figure><p>Every developer has received a bug report like this at least once:</p><blockquote>It doesn’t work.<br>Please check.</blockquote><p>Or maybe:</p><blockquote>The page is broken.<br>I clicked something and got an error</blockquote><p>And to be fair, I don’t think people send reports like this because they don’t care.</p><p>Most of the time, they just don’t know what information is useful for debugging. A user sees a broken page. A QA tester sees something unexpected. A product manager gets feedback from a client. From their side, the problem is obvious: “something is wrong”.</p><p>But from the developer’s side, that is usually only the beginning.</p><p>Which page?<br>Which user?<br>Which browser?<br>What did you click before that?<br>Did it happen once or every time?<br>Was there a failed API request?<br>Any console error?<br>Can I reproduce it locally?</p><p>And suddenly a small bug turns into a long Slack thread.</p><h3>The real cost of unclear bug reports</h3><p>Bad bug reports don’t just make developers unhappy.</p><p>They create extra work for everyone.</p><p>The developer has to ask follow-up questions.<br>The QA tester has to reproduce the issue again.<br>The product manager has to clarify what was expected.<br>The user may have already closed the page and forgotten the exact steps.</p><p>I’ve seen this many times in real projects. The bug itself can be small, but because the initial report has almost no context, the investigation takes much longer than it should.</p><p>A report like this is hard to work with:</p><blockquote>Checkout doesn’t work.</blockquote><p>t may mean anything.</p><p>Maybe the button is disabled.<br>Maybe the API returns 500.<br>Maybe the user has no permission.<br>Maybe the frontend crashed.<br>Maybe the payment provider is down.<br>Maybe the issue happens only with one specific product in the cart.</p><p>Now compare it with this:</p><blockquote>On the checkout page, after clicking “Pay”, the button keeps loading and the order is not created.<br>URL: /checkout<br>Browser: Chrome<br>Steps: opened cart → clicked checkout → filled the form → clicked pay<br>Console error: Cannot read properties of undefined<br>Failed request: POST /api/orders returned 500</blockquote><p>This is not perfect. But it is already useful.</p><p>As a developer, I know where to start.</p><h3>A good bug report does not need to be long</h3><p>One common mistake is thinking that a good bug report has to be detailed and formal.</p><p>It doesn’t.</p><p>A good bug report just needs enough context to help someone reproduce or investigate the issue.</p><p>In most cases, I want to know a few basic things:</p><ul><li>where it happened</li><li>what the user did before the issue</li><li>what actually happened</li><li>what was expected</li><li>what browser or environment was used</li><li>whether there were console or network errors</li><li>whether there is a screenshot or short recording</li></ul><p>That’s usually enough to start.</p><h3>The page URL is more important than people think</h3><p>“Dashboard is broken” sounds clear, but in most SaaS products there are many dashboards, filters, roles, tabs, and states.</p><p>The exact URL often tells much more than a description.</p><p>For example:</p><pre>https://example.com/dashboard/reports/123?status=failed</pre><p>From this alone, a developer may understand that the bug is related to a specific report, filter, user permission, or route.</p><p>Without the URL, you often start by guessing.</p><p>And guessing is not debugging.</p><h3>Steps to reproduce are still the most useful part</h3><p>If I could choose only one thing to improve in most bug reports, I would choose steps to reproduce.</p><p>They don’t need to be beautifully written.</p><p>Something like this is already helpful:</p><ol><li>Opened the reports page</li><li>Clicked “Create report”</li><li>Uploaded a PDF file</li><li>Clicked “Export”</li><li>Got an error</li></ol><p>That small list can save a lot of time.</p><p>Sometimes the bug is not in the final action. It happened because of something the user did two or three steps before.</p><p>Without steps, the developer only sees the result, not the path.</p><h3>Screenshots help, but they are not enough</h3><p>Screenshots are useful. I like screenshots in bug reports.</p><p>They are great for visual problems:</p><ul><li>broken layout</li><li>missing button</li><li>wrong text</li><li>empty state</li><li>modal positioned incorrectly</li><li>unexpected UI behavior</li></ul><p>But screenshots have a limit.</p><p>A screenshot of a blank page only tells me that the page is blank.</p><p>It doesn’t tell me why.</p><p>Was there a frontend exception?<br>Did the API return 403?<br>Did a request timeout?<br>Was the user redirected incorrectly?<br>Did some data come back in an unexpected format?</p><p>For technical bugs, a screenshot is much more useful when it comes with console errors and failed network requests.</p><h3>Console and network errors are often the shortcut</h3><p>Many frontend bugs leave clues in the browser.</p><p>A console error like:</p><pre>TypeError: Cannot read properties of null</pre><p>or a failed request like:</p><pre>POST /api/orders returned 500</pre><p>can immediately point the investigation in the right direction.</p><p>The problem is that most people who report bugs are not developers.</p><p>They don’t know how to open DevTools.<br>They don’t know which tab to check.<br>They don’t know what to copy.<br>And honestly, they should not need to know this.</p><p>This is exactly the type of context that should be collected automatically.</p><h3>A simple bug report template</h3><p>For small teams, I usually prefer a simple format like this:</p><pre>Title:<br>Short description of the issue</pre><pre>URL:<br>Where the bug happened</pre><pre>Steps:<br>1.<br>2.<br>3.</pre><pre>Actual result:<br>What happened</pre><pre>Expected result:<br>What should have happened</pre><pre>Environment:<br>Browser, OS, screen size</pre><pre>Attachments:<br>Screenshot or video if available</pre><pre>Technical context:<br>Console errors and failed network requests if available</pre><p>Nothing fancy.</p><p>No huge form.<br>No enterprise process.<br>No unnecessary fields.</p><p>Just the information that helps the team move faster.</p><h3>The best bug report is the one that is easy to create</h3><p>The problem with templates is that people often stop using them.</p><p>Not because they are bad.<br>But because filling them manually is boring.</p><p>Nobody wants to copy the URL, browser version, screen size, console errors, failed requests, and steps every time something breaks.</p><p>So in practice, the best bug reporting workflow is the one that makes the useful context almost automatic.</p><p>The person reporting the bug should mostly explain what they saw.</p><p>The tool should collect the technical details:</p><ul><li>page URL</li><li>screenshot</li><li>browser info</li><li>viewport size</li><li>user steps</li><li>console errors</li><li>failed network requests</li></ul><p>This reduces back-and-forth and makes reports easier to investigate.</p><h3>I built a small tool for this</h3><p>This problem annoyed me enough that I built a small Chrome extension called <strong>BugTrace</strong>.</p><p>The idea is simple:</p><ol><li>Something breaks</li><li>The user clicks the extension</li><li>Adds a short description</li><li>BugTrace captures the useful context</li><li>A structured bug report can be shared with the team</li></ol><p>It is not trying to replace Jira, Linear, GitHub Issues, or any existing tracker.</p><p>It is more like a lightweight capture layer before the task gets created somewhere else.</p><p>BugTrace can collect the page URL, screenshot, browser details, user steps, console errors, and failed network requests, so the report is more useful from the beginning.</p><p>You can try it here:</p><p>Chrome Web Store: <a href="https://chromewebstore.google.com/detail/bugtrace/hhojlolhokmpogefcfkjbibmpaglfgpo">https://chromewebstore.google.com/detail/bugtrace/hhojlolhokmpogefcfkjbibmpaglfgpo</a><br>Landing page: <a href="https://bugtrace-viewer.pages.dev/">https://bugtrace-viewer.pages.dev/</a></p><h3>Final thought</h3><p>A good bug report is not about writing a lot of text.</p><p>It is about giving the right context.</p><p>The faster a developer can understand what happened, where it happened, and what clues the browser left behind, the faster the issue can be fixed.</p><p>So when someone sends:</p><blockquote>It doesn’t work.</blockquote><p>I don’t think the right answer is to blame them.</p><p>The better answer is to make reporting bugs easier.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=da238c9c4feb" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[When Docstrings Become Technical Debt (and How to Write Ones That Actually Help)]]></title>
            <link>https://medium.com/@progsly/when-docstrings-become-technical-debt-and-how-to-write-ones-that-actually-help-6706d2dbdcd0?source=rss-94fbaaa88f------2</link>
            <guid isPermaLink="false">https://medium.com/p/6706d2dbdcd0</guid>
            <category><![CDATA[developer-experience]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[clean-code]]></category>
            <dc:creator><![CDATA[Sergey Kovalchuk]]></dc:creator>
            <pubDate>Fri, 24 Apr 2026 09:06:30 GMT</pubDate>
            <atom:updated>2026-04-24T09:06:30.374Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="Good docstrings survive refactoring. Bad ones just look structured." src="https://cdn-images-1.medium.com/max/1024/1*DQQtIDFQJUl6EsA68RKmvQ.png" /></figure><h4>Intro</h4><p>I recently opened a function with a perfect Google-style docstring: neatly formatted Args, Returns, and Raises. It looked like documentation you’d trust.</p><p>Then I read the code.</p><p>The function signature had changed. Parameters were renamed. One was removed entirely. The Raises section described behavior that no longer existed.</p><p>The docstring was clean, structured, and completely misleading.</p><p><strong>We tend to trust docstrings more than code. And that’s exactly why they’re dangerous.</strong></p><h4>The core idea</h4><p><strong>Docstrings that only describe <em>what</em> the code does tend to become technical debt.<br>Docstrings that explain <em>why</em> tend to remain useful documentation.</strong></p><p>It’s a small distinction on paper, but a big one in practice.</p><h4>What the code already tells you</h4><p>In most modern codebases, the code already communicates a lot:</p><ul><li>function names describe intent</li><li>type hints show inputs and outputs</li><li>return types are explicit</li><li>structure reveals behavior</li></ul><p>But code rarely explains:</p><ul><li>why this approach was chosen</li><li>hidden constraints or invariants</li><li>edge-case reasoning</li><li>historical decisions</li><li>what <em>not</em> to change</li></ul><p>Docstrings that repeat the first part decay quickly.<br>Docstrings that capture the second part save real time.</p><h4>Example</h4><pre># Redundant docstring<br>def get_active_users(tenant_id: str) -&gt; list[User]:<br>    &quot;&quot;&quot;Get active users for a tenant.<br><br>    Args:<br>        tenant_id: The tenant ID.<br><br>    Returns:<br>        A list of users.<br>    &quot;&quot;&quot;</pre><pre># Useful documentation<br>def get_active_users(tenant_id: str) -&gt; list[User]:<br>    &quot;&quot;&quot;Active = logged in within 90 days AND not soft-deleted.<br><br>    Mirrors the /users public API filter, NOT the admin panel<br>    (admin panel includes soft-deleted).<br><br>    If you need admin semantics, use get_all_users_for_admin().<br>    &quot;&quot;&quot;</pre><p>The second version answers questions that actually come up in real usage.</p><h4>Where Google-style docstrings go wrong</h4><p>Google-style docstrings are not the problem. Misuse is.</p><p>They often create the illusion of documentation:</p><ul><li>Args encourages describing obvious parameters</li><li>Returns duplicate type hints</li><li>Raises become outdated very quickly</li></ul><p>The result:</p><ul><li>looks clean</li><li>passes code review</li><li>silently rots</li></ul><p>The format isn’t bad, but it shouldn’t replace thinking.</p><h4>A simple test (The Rot Test)</h4><p>Here’s a quick rule I use:</p><blockquote><em>If I change the function signature or types, what happens to the docstring?</em></blockquote><ul><li>if it breaks alongside the code → it describes <em>what</em></li><li>if it stays but becomes incorrect → it’s dangerous</li><li>if it remains valid → it describes <em>why</em></li></ul><p>That last category is what you want.</p><h4>Why this matters in practice</h4><p>Outdated docstrings aren’t harmless.</p><p>They:</p><ul><li>lead to incorrect API usage</li><li>create false assumptions</li><li>slow down onboarding and debugging</li><li>hide real behavior changes</li></ul><p><strong>The most dangerous docstrings are not the missing ones.<br>They are the ones that look correct.</strong></p><h4>Where “self-documenting code” breaks down</h4><p>Minimalism works — but not everywhere.</p><p>Docstrings are valuable when:</p><ul><li>the function is part of a public API or SDK</li><li>reading the implementation is expensive</li><li>business logic is non-trivial</li><li>side effects are not obvious</li><li>decisions depend on historical context</li></ul><p>If the reader shouldn’t read the implementation — context matters.</p><h4>A note on AI-generated docstrings</h4><p>This problem is getting worse.</p><p>Tools like GitHub Copilot generate docstrings that are:</p><ul><li>perfectly formatted</li><li>stylistically correct</li><li>mostly describing <em>what the code does</em></li></ul><p>Which means:</p><ul><li>more text</li><li>not more documentation</li></ul><p>It creates the illusion of quality without adding context.</p><h4>Practical checklist</h4><p>Write a docstring if:</p><ul><li>the function is part of a public API</li><li>there is a non-obvious constraint or invariant</li><li>there is historical context</li><li>there are similar functions with different semantics</li><li>edge-case behavior is not intuitive</li><li>removing the docstring would make the <em>why</em> unclear</li></ul><p>Avoid writing one if:</p><ul><li>it repeats the function name</li><li>Args duplicates the signature</li><li>Returns duplicates the type</li><li>it’s written “just because it’s expected”</li></ul><h4>Exceptions (important)</h4><p>There are valid cases where describing <em>what</em> is useful:</p><ul><li>public libraries</li><li>auto-generated documentation (e.g. Swagger, Sphinx)</li><li>SDKs where users don’t read the implementation</li></ul><p>Even there, adding <em>why</em> is what makes it valuable.</p><h4>Closing</h4><p>A docstring is a promise: <em>“you can trust this.”</em></p><p>That promise is expensive to maintain. And if it’s not maintained, it turns into misinformation.</p><p>Sometimes, no docstring is better than a misleading one.</p><p><strong>A good docstring doesn’t describe the code.<br>It preserves the context that the code cannot express.</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6706d2dbdcd0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to Optimize SQLAlchemy Queries with CTEs (and Avoid the 32767 Arguments Limit)]]></title>
            <link>https://medium.com/@progsly/how-to-optimize-sqlalchemy-queries-with-ctes-and-avoid-the-32767-arguments-limit-7625b4c59dc5?source=rss-94fbaaa88f------2</link>
            <guid isPermaLink="false">https://medium.com/p/7625b4c59dc5</guid>
            <category><![CDATA[sql]]></category>
            <category><![CDATA[sqlalchemy]]></category>
            <category><![CDATA[optimization]]></category>
            <category><![CDATA[postgresql]]></category>
            <category><![CDATA[python]]></category>
            <dc:creator><![CDATA[Sergey Kovalchuk]]></dc:creator>
            <pubDate>Tue, 26 Aug 2025 08:53:57 GMT</pubDate>
            <atom:updated>2025-08-26T08:53:57.546Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*C3woYjup9KjGsUcTp_QO5w.png" /></figure><p>When working with large datasets in SQLAlchemy, you might hit an infamous PostgreSQL error:</p><pre>psycopg2.ProgrammingError: the number of query arguments cannot exceed 32767</pre><p>This happens when you try to filter with a huge list of IDs, for example:</p><pre>query = db.session.query(User).filter(User.id.in_(big_list_of_ids))</pre><p>If big_list_of_ids contains <strong>30,000+ elements</strong>, PostgreSQL refuses to execute it.</p><p>The good news: <strong>Common Table Expressions (CTEs)</strong> can help us bypass this limitation, while keeping the query efficient and readable.</p><h4>Problem Example: Too Many Parameters</h4><pre>big_list_of_ids = [177093, 177094, 177095, ...]  # 40k+ elements<br><br>query = (<br>    db.session.query(User)<br>    .filter(User.id.in_(big_list_of_ids))<br>)<br>results = query.all()</pre><p>This generates something like:</p><pre>SELECT users.id, users.name, ...<br>FROM users<br>WHERE users.id IN (177093, 177094, 177095, ... 40000+ IDs ...)</pre><p>And once the list exceeds 32,767 elements → error.</p><h4>Solution: Use a CTE Instead of a Huge IN</h4><p>Instead of passing a massive list as arguments, we can <strong>send the list as an array</strong> and expand it with unnest() inside a CTE.</p><p><strong>SQLAlchemy Core Example</strong></p><pre>from sqlalchemy import select, literal_column<br>from sqlalchemy.dialects.postgresql import array<br><br>big_list_of_ids = [177093, 177094, 177095, ...]<br><br>ids_cte = (<br>    select([literal_column(&quot;unnest(:ids)&quot;).label(&quot;id&quot;)])<br>    .cte(&quot;ids_cte&quot;)<br>    .params(ids=big_list_of_ids)<br>)<br><br>query = (<br>    select([User])<br>    .select_from(User.__table__.join(ids_cte, User.id == ids_cte.c.id))<br>)<br><br>results = db.session.execute(query).fetchall()</pre><p>Generated SQL:</p><pre>WITH ids_cte AS (<br>    SELECT unnest(:ids) AS id<br>)<br>SELECT users.id, users.name, ...<br>FROM users<br>JOIN ids_cte ON users.id = ids_cte.id</pre><p>Where :ids is a single PostgreSQL array parameter like {177093,177094,177095,...}.</p><p>No more 32k argument limit.</p><h4>ORM Example with CTE</h4><pre>from sqlalchemy import func<br><br>ids_cte = (<br>    db.session.query(func.unnest(big_list_of_ids).label(&quot;id&quot;))<br>    .cte(&quot;ids_cte&quot;)<br>)<br><br>query = (<br>    db.session.query(User)<br>    .join(ids_cte, User.id == ids_cte.c.id)<br>)<br><br>results = query.all()</pre><p>Generated SQL:</p><pre>WITH ids_cte AS (<br>    SELECT unnest(ARRAY[177093, 177094, 177095, ...]) AS id<br>)<br>SELECT users.id, users.name, ...<br>FROM users<br>JOIN ids_cte ON users.id = ids_cte.id</pre><h4>Other Optimization Use Cases</h4><p><strong>Example: Counting Orders per User</strong></p><p><strong>Without CTE (correlated subquery):</strong></p><pre>query = (<br>    db.session.query(<br>        User.id,<br>        User.name,<br>        db.session.query(func.count(Order.id))<br>        .filter(Order.user_id == User.id)<br>        .label(&quot;order_count&quot;)<br>    )<br>)</pre><p>Generated SQL:</p><pre>SELECT users.id, users.name,<br>       (SELECT count(orders.id) <br>        FROM orders <br>        WHERE orders.user_id = users.id) AS order_count<br>FROM users</pre><p>⚠️ Problem: runs a subquery <strong>per row</strong>.</p><p><strong>With CTE:</strong></p><pre>orders_cte = (<br>    db.session.query(<br>        Order.user_id,<br>        func.count(Order.id).label(&quot;order_count&quot;)<br>    )<br>    .group_by(Order.user_id)<br>    .cte(&quot;orders_cte&quot;)<br>)<br><br>query = (<br>    db.session.query(User.id, User.name, orders_cte.c.order_count)<br>    .outerjoin(orders_cte, orders_cte.c.user_id == User.id)<br>)</pre><p>Generated SQL:</p><pre>WITH orders_cte AS (<br>    SELECT orders.user_id, count(orders.id) AS order_count<br>    FROM orders<br>    GROUP BY orders.user_id<br>)<br>SELECT users.id, users.name, orders_cte.order_count<br>FROM users<br>LEFT OUTER JOIN orders_cte ON orders_cte.user_id = users.id</pre><p>✅ Orders are aggregated once, then joined. Much more efficient.</p><h4>Wrap Up</h4><ul><li>.in_() with thousands of IDs is dangerous — you’ll hit PostgreSQL’s <strong>32767 parameter limit</strong>.</li><li>Use a <strong>CTE + </strong><strong>unnest()</strong>: send IDs as a single array instead of thousands of parameters.</li><li>CTEs are also great for performance tuning (aggregations, pagination, reusable subqueries).</li><li>Always check with EXPLAIN to see the difference.</li></ul><p>Next time you face the number of query arguments cannot exceed 32767, wrap your IDs in a CTE and you’re safe.</p><h4>Bonus: Helper Function for Filtering by IDs</h4><p>Instead of writing custom logic every time, you can make a reusable helper that decides:</p><ul><li>If the list of IDs is <strong>small (&lt; 10k)</strong> → use .in_() (fast and simple).</li><li>If the list of IDs is <strong>large (&gt;= 10k)</strong> → use unnest() via CTE to avoid PostgreSQL’s <strong>32767 argument limit</strong>.</li></ul><p><strong>Implementation</strong></p><pre>from sqlalchemy import func, select<br><br>def filter_by_ids(query, column, ids, chunk_limit=10000):<br>    &quot;&quot;&quot;<br>    Smart filter by IDs that avoids PostgreSQL&#39;s 32767 argument limit.<br>    <br>    Args:<br>        query: SQLAlchemy query object<br>        column: SQLAlchemy column (e.g., User.id)<br>        ids: list of IDs (Python list)<br>        chunk_limit: threshold to switch from IN to CTE<br>    <br>    Returns:<br>        Updated query object<br>    &quot;&quot;&quot;<br>    if not ids:<br>        return query.filter(False)  # return empty result if no IDs<br><br>    # Case 1: small number of IDs -&gt; use IN<br>    if len(ids) &lt; chunk_limit:<br>        return query.filter(column.in_(ids))<br><br>    # Case 2: large number of IDs -&gt; use unnest + CTE<br>    ids_cte = (<br>        select(func.unnest(ids).label(&quot;id&quot;))<br>        .cte(&quot;ids_cte&quot;)<br>    )<br>    return query.join(ids_cte, column == ids_cte.c.id)</pre><p><strong>Usage Example</strong></p><pre>big_list_of_ids = [177093, 177094, 177095, ...]  # 40k+ IDs<br><br>query = db.session.query(User)<br>query = filter_by_ids(query, User.id, big_list_of_ids)<br><br>results = query.all()</pre><p><strong>Generated SQL (when IDs are large)</strong></p><pre>WITH ids_cte AS (<br>    SELECT unnest(ARRAY[177093, 177094, 177095, ...]) AS id<br>)<br>SELECT users.id, users.name, ...<br>FROM users<br>JOIN ids_cte ON users.id = ids_cte.id</pre><p>This way you <strong>never hit the 32767 argument limit</strong>, and you don’t have to think about it anymore — the helper handles it automatically.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7625b4c59dc5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a PDF Diff Checker in Python: Text and Visual Differences]]></title>
            <link>https://medium.com/@progsly/building-a-pdf-diff-checker-in-python-text-and-visual-differences-ead769fbacd9?source=rss-94fbaaa88f------2</link>
            <guid isPermaLink="false">https://medium.com/p/ead769fbacd9</guid>
            <category><![CDATA[pdf]]></category>
            <category><![CDATA[python-programming]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[fastapi]]></category>
            <category><![CDATA[compare-document]]></category>
            <dc:creator><![CDATA[Sergey Kovalchuk]]></dc:creator>
            <pubDate>Mon, 25 Aug 2025 09:13:05 GMT</pubDate>
            <atom:updated>2025-08-25T09:13:05.461Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lNjgbPZWIthMd3hzAk2QZQ.png" /></figure><p>When working with contracts, reports, or specifications, it’s often necessary to compare two versions of the same PDF. Did the numbers change? Was an extra paragraph added? Or maybe the layout was modified slightly?</p><p>In this article, I’ll show you how to build a <strong>simple PDF diff checker</strong> in Python. We’ll cover both <strong>textual differences</strong> and <strong>visual differences</strong>, and generate a combined PDF report with highlighted changes.</p><h4>Don’t want to code it yourself?</h4><p>If you just need a quick way to compare two PDF documents without writing Python scripts, I built a free Chrome extension: <a href="https://chromewebstore.google.com/detail/compare-pdf-tool/cobkffhdclimlamjmdkchlcemhbpppka"><strong>Compare PDF Tool</strong></a></p><p>With it, you can upload two PDFs directly in your browser and see the differences side by side. Perfect if you’re not in the mood to set up a Python environment.</p><h4>Tools We’ll Use</h4><ul><li><strong>PyPDF2</strong> — extract text from PDFs.</li><li><strong>difflib</strong> — compute text differences.</li><li><strong>pdf2image + Pillow (PIL)</strong> — render PDFs into images and highlight changes.</li><li><strong>reportlab</strong> — generate a PDF with the results.</li><li><strong>FastAPI</strong> — expose a small API to upload and compare files.</li></ul><h4>Step 1: Extracting Text and Comparing</h4><p>Text diff is the most straightforward:</p><ol><li>Load both PDFs.</li><li>Extract text page by page.</li><li>Normalize whitespace.</li><li>Use difflib to compute differences.</li></ol><pre>from PyPDF2 import PdfReader<br>import difflib<br><br>def extract_text(pdf_bytes):<br>    reader = PdfReader(io.BytesIO(pdf_bytes))<br>    return &quot;&quot;.join(page.extract_text() for page in reader.pages)<br><br>def compare_text(pdf1, pdf2):<br>    text1, text2 = extract_text(pdf1), extract_text(pdf2)<br>    diff = difflib.unified_diff(<br>        text1.splitlines(),<br>        text2.splitlines(),<br>        fromfile=&quot;before.pdf&quot;,<br>        tofile=&quot;after.pdf&quot;,<br>    )<br>    return list(diff)</pre><p>Output will look like a standard git-style diff, where - means removed, + means added.</p><h4>Step 2: Visual Differences</h4><p>Sometimes text stays the same, but formatting, tables, or images change. For that, we render both PDFs as images and compare them pixel by pixel.</p><p>A simple approach is to use ImageChops.difference from Pillow:</p><pre>from PIL import ImageChops, ImageDraw<br><br>def compare_images(img1, img2):<br>    diff = ImageChops.difference(img1, img2)<br>    if diff.getbbox():<br>        annotated = img1.copy()<br>        draw = ImageDraw.Draw(annotated)<br>        # mark changed pixels with rectangles<br>        for x in range(0, img1.width, 10):<br>            for y in range(0, img1.height, 10):<br>                if diff.getpixel((x, y)) != (0, 0, 0):<br>                    draw.rectangle([x, y, x+5, y+5], outline=&quot;red&quot;)<br>        return annotated<br>    return None</pre><p>This isn’t pixel-perfect (too granular), but good enough for highlighting layout or formatting changes.</p><h4>Step 3: Generating a Combined Report</h4><p>To make results easier to read, we combine <strong>before</strong> and <strong>after</strong> pages side by side and add the highlighted diff.</p><p>Using <strong>reportlab</strong>, we can generate a wide PDF:</p><pre>from reportlab.pdfgen import canvas<br>from reportlab.lib.pagesizes import letter<br><br>def save_diff_report(images_before, images_after, images_diff, file_path):<br>    c = canvas.Canvas(file_path, pagesize=(letter[0] * 2, letter[1]))<br>    for before, after, diff in zip(images_before, images_after, images_diff):<br>        # merge into a wide PNG first...<br>        # then place into PDF page<br>        c.drawImage(diff, 0, 0, width=letter[0] * 2, height=letter[1])<br>        c.showPage()<br>    c.save()</pre><p>Now we have a <strong>“before” + “after” + highlighted diff</strong> PDF ready to download.</p><h4>Step 4: Wrapping in a FastAPI Service</h4><p>Finally, let’s expose this functionality via API:</p><pre>from fastapi import FastAPI, UploadFile<br>import json<br><br>app = FastAPI()<br><br>@app.post(&quot;/compare&quot;)<br>def compare_files(file1: UploadFile, file2: UploadFile):<br>    # 1. Extract text diff<br>    # 2. Generate visual diff images<br>    # 3. Save combined PDF<br>    result = {<br>        &quot;text_diff&quot;: [&quot;- old text&quot;, &quot;+ new text&quot;],<br>        &quot;diff_pdf&quot;: &quot;wide_diff-123.pdf&quot;,<br>    }<br>    return json.dumps(result)</pre><p>And a second endpoint for downloading the result:</p><pre>@app.get(&quot;/download/{name}&quot;)<br>def download_pdf(name: str):<br>    return FileResponse(f&quot;./results/{name}&quot;, media_type=&quot;application/pdf&quot;)</pre><h4>Improvements for Later</h4><ul><li>Smarter visual diff using OpenCV contours instead of per-pixel comparisons.</li><li>OCR (Tesseract) for scanned PDFs.</li><li>Ignore headers/footers with regex filters.</li><li>Frontend UI with side-by-side viewer.</li></ul><h4>Wrap Up</h4><p>With less than ~200 lines of Python, you can build a working PDF diff checker that highlights both <strong>text</strong> and <strong>visual changes</strong>.</p><p>This approach is powerful for:</p><ul><li>QA teams validating reports.</li><li>Lawyers comparing contract revisions.</li><li>Developers reviewing generated PDFs.</li></ul><p>If you don’t want to write code, you can also try my <a href="https://chromewebstore.google.com/detail/compare-pdf-tool/cobkffhdclimlamjmdkchlcemhbpppka"><strong>Compare PDF Tool Chrome extension</strong></a> to instantly compare PDFs directly in your browser.</p><p>Next step? Wrap your Python solution in Docker and deploy — now you’ve got a micro-SaaS idea ready to test. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ead769fbacd9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Evolution of Functions in Python: From Python 2.7 to Today]]></title>
            <link>https://medium.com/@progsly/evolution-of-functions-in-python-from-python-2-7-to-today-e227bc585810?source=rss-94fbaaa88f------2</link>
            <guid isPermaLink="false">https://medium.com/p/e227bc585810</guid>
            <category><![CDATA[python-example]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[python-programming]]></category>
            <category><![CDATA[python2-vs-python3]]></category>
            <category><![CDATA[python]]></category>
            <dc:creator><![CDATA[Sergey Kovalchuk]]></dc:creator>
            <pubDate>Mon, 18 Aug 2025 13:10:57 GMT</pubDate>
            <atom:updated>2025-08-18T13:10:57.095Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/601/1*PPIp7twJJUknfohZqtL8pQ.png" /></figure><p>Python, with its rich history, is constantly evolving. One of the most noticeable aspects of this evolution is the <strong>function declaration syntax</strong> and the introduction of <strong>type hints</strong>. Let’s trace how function syntax and capabilities have changed across popular Python versions.</p><p>We will use a simple function as an example. It takes multiple arguments, arbitrary positional (*args) and keyword (**kwargs) arguments, prints them, and returns a string.</p><h4>Python 2.7: Classic Approach</h4><p>In Python 2.7, everything was straightforward and loosely typed. Data types existed but were <strong>not part of function syntax</strong>. The main tool for documenting types was <strong>docstrings</strong>.</p><pre># Python 2.7<br>def process_data(user_id, items, *args, **kwargs):<br>    &quot;&quot;&quot;<br>    Processes user data and items.<br><br>    :param user_id: ID of the user (int)<br>    :param items: A list of items (list)<br>    :param args: Extra positional arguments<br>    :param kwargs: Extra keyword arguments (e.g., verbose=True)<br>    :return: A status message (str)<br>    &quot;&quot;&quot;<br>    print &quot;User ID:&quot;, user_id<br>    print &quot;Items:&quot;, items<br>    print &quot;Additional args:&quot;, args<br>    print &quot;Additional kwargs:&quot;, kwargs<br><br>    if kwargs.get(&quot;verbose&quot;):<br>        print &quot;Processing in verbose mode.&quot;<br><br>    return &quot;Processed %d items for user %d&quot; % (len(items), user_id)<br><br># Example call<br>print process_data(101, [&#39;apple&#39;, &#39;banana&#39;], &#39;extra_arg&#39;, verbose=True)</pre><p><strong>Key features of Python 2.7:</strong></p><ul><li>No native type hints; types documented only in docstrings.</li><li>print is a <strong>statement</strong>, not a function.</li><li>String formatting uses % or .format().</li></ul><h4>Python 3.0–3.4: First Function Annotations</h4><p>Python 3.0 introduced <strong>function annotations</strong> (PEP 3107), allowing type hints in function signatures. They were <strong>only for documentation</strong> and not enforced.</p><pre># Python 3.4<br>def process_data(user_id: int, items: list, *args, **kwargs) -&gt; str:<br>    &quot;&quot;&quot;Processes user data and items.&quot;&quot;&quot;<br>    print(&quot;User ID:&quot;, user_id)<br>    print(&quot;Items:&quot;, items)<br>    print(&quot;Additional args:&quot;, args)<br>    print(&quot;Additional kwargs:&quot;, kwargs)<br><br>    if kwargs.get(&quot;verbose&quot;):<br>        print(&quot;Processing in verbose mode.&quot;)<br><br>    return &quot;Processed {} items for user {}&quot;.format(len(items), user_id)<br><br># Example call<br>print(process_data(101, [&#39;apple&#39;, &#39;banana&#39;], &#39;extra_arg&#39;, verbose=True))</pre><p><strong>Key points (3.0–3.4):</strong></p><ul><li>Annotations exist but are <strong>not enforced</strong>.</li><li>print is a <strong>function</strong>.</li><li>String formatting uses .format() or %.</li></ul><h4>Python 3.5: Typing Revolution</h4><p>Python 3.5 (PEP 484) standardized type hints and introduced the typing module, allowing complex types like List, Dict, and Any.</p><pre># Python 3.5<br>from typing import List, Any<br><br>def process_data(user_id: int, items: List[str], *args: Any, **kwargs: Any) -&gt; str:<br>    &quot;&quot;&quot;Processes user data and items.&quot;&quot;&quot;<br>    print(&quot;User ID:&quot;, user_id)<br>    print(&quot;Items:&quot;, items)<br>    print(&quot;Additional args:&quot;, args)<br>    print(&quot;Additional kwargs:&quot;, kwargs)<br><br>    if kwargs.get(&quot;verbose&quot;):<br>        print(&quot;Processing in verbose mode.&quot;)<br><br>    return &quot;Processed {} items for user {}&quot;.format(len(items), user_id)<br><br># Example call<br>print(process_data(101, [&#39;apple&#39;, &#39;banana&#39;], &#39;extra_arg&#39;, verbose=True))</pre><p><strong>Key changes:</strong></p><ul><li>Standardized type hints via typing.</li><li>Can use List, Dict, Any for complex types.</li><li><strong>f-strings not yet available</strong> (added in 3.6).</li></ul><h4>Python 3.6: f-Strings</h4><p>Python 3.6 introduced <strong>f-strings</strong> (PEP 498) for easier and more readable string formatting.</p><pre># Python 3.6<br>from typing import List, Any<br><br>def process_data(user_id: int, items: List[str], *args: Any, **kwargs: Any) -&gt; str:<br>    &quot;&quot;&quot;Processes user data and items.&quot;&quot;&quot;<br>    print(f&quot;User ID: {user_id}&quot;)<br>    print(f&quot;Items: {items}&quot;)<br>    print(f&quot;Additional args: {args}&quot;)<br>    print(f&quot;Additional kwargs: {kwargs}&quot;)<br><br>    if kwargs.get(&quot;verbose&quot;):<br>        print(&quot;Processing in verbose mode.&quot;)<br><br>    return f&quot;Processed {len(items)} items for user {user_id}&quot;<br><br># Example call<br>print(process_data(101, [&#39;apple&#39;, &#39;banana&#39;], &#39;extra_arg&#39;, verbose=True))</pre><h4>Python 3.9: Simplifying Collection Types</h4><p>Python 3.9 (PEP 585) allowed using <strong>built-in collection types</strong> (list, dict, tuple) in type hints instead of typing.List or typing.Dict.</p><pre># Python 3.9<br>from typing import Any<br><br>def process_data(user_id: int, items: list[str], *args: Any, **kwargs: Any) -&gt; str:<br>    &quot;&quot;&quot;Processes user data and items.&quot;&quot;&quot;<br>    print(f&quot;User ID: {user_id}&quot;)<br>    print(f&quot;Items: {items}&quot;)<br>    print(f&quot;Additional args: {args}&quot;)<br>    print(f&quot;Additional kwargs: {kwargs}&quot;)<br><br>    if kwargs.get(&quot;verbose&quot;):<br>        print(&quot;Processing in verbose mode.&quot;)<br><br>    return f&quot;Processed {len(items)} items for user {user_id}&quot;<br><br># Example call<br>print(process_data(101, [&#39;apple&#39;, &#39;banana&#39;], &#39;extra_arg&#39;, verbose=True))</pre><p><strong>Key changes:</strong></p><ul><li>Use list[str], dict[str, int] directly.</li><li>Any still comes from typing.</li></ul><h4>Python 3.10+: Union Types with |</h4><p>Python 3.10 (PEP 604) introduced the | operator for <strong>union types</strong>.</p><pre># Python 3.10+<br>from typing import Any<br><br>def process_data(user_id: int | str, items: list[str], *args: Any, **kwargs: Any) -&gt; str:<br>    &quot;&quot;&quot;Processes user data and items.&quot;&quot;&quot;<br>    safe_user_id = int(user_id)<br>    print(f&quot;User ID: {safe_user_id}&quot;)<br>    print(f&quot;Items: {items}&quot;)<br>    print(f&quot;Additional args: {args}&quot;)<br>    print(f&quot;Additional kwargs: {kwargs}&quot;)<br><br>    if kwargs.get(&quot;verbose&quot;):<br>        print(&quot;Processing in verbose mode.&quot;)<br><br>    return f&quot;Processed {len(items)} items for user {safe_user_id}&quot;<br><br># Example call<br>print(process_data(&quot;101&quot;, [&#39;apple&#39;, &#39;banana&#39;], &#39;extra_arg&#39;, verbose=True))</pre><p><strong>Key changes:</strong></p><ul><li>int | str replaces Union[int, str].</li><li>Can write int | None instead of Optional[int].</li><li>New types for static analysis: Literal, TypeGuard, etc.</li></ul><h4>Conclusion</h4><p>The evolution of Python function syntax shows the journey from <strong>implicit documentation</strong> to a <strong>powerful static typing system</strong>. Modern syntax improves code readability, reduces errors, and makes Python suitable for both beginners and professional projects.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e227bc585810" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>